Card Isle Embed Documentation

Easily offer Card Isle cards within your Ecommerce platform.


Bring your customers access to Card Isle's collection of over 10,000 greeting card designs and the ability to upload personal photos. Simply drop in a few lines of code to your website, and install a plug-and-play printer at your fulfillment center.



Your card:



Your message:

Artist signature:

Embedded iframe Documentation

Our goal is to make this easy

If you have any questions, please don't hesitate to reach out to info@cardisle.com.


Overview of the integration

Step 1. Add the option for personalized greeting cards to your website.

Step 2. Customers simply select and personalize a card, and also have the option to upload their own photos.

Step 3. Cards are printed on-demand in your fulfillment center and included in the box with your customer's order.


Required components

Our greeting card iframe allows your customers to design cards without ever leaving your website. This iframe--and all of its functionality--are dynamically added to your site by the shop_embed.js library. All three components necessary for the integration are listed below:

Javascript library: All functionality for the embedded iframe is included in this library: https://s3.amazonaws.com/cardisle.web/static/ecommerce/shop_embed.js

Card Isle Button: Assigning the class card-isle-button to a clickable element (e.g. button, div, a, etc.) provides an anchor for the Javascript library.

Event Listener: The Card Isle iframe will communicate details of your customer's card selection through a message that can be captured via an event listener.


A simple demonstration

The intention of this demo is to provide you with a simple--but complete--example of how the Card Isle integration can be built.

<html>
<head>
<style>
  img {
    width: 100px;
    display: block;
    border: solid 1px gray;
    margin: 10px 0;
  }
</style>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<!-- import the Card Isle Javascript library -->
<script src="https://s3.amazonaws.com/cardisle.web/static/ecommerce/shop_embed.js"></script>
</head>
<body>
  <button type="button" class="card-isle-button">DEMO: Click me</button>
<script>
  $(document).ready(function() {
          // initiate Card Isle functionality after the page has loaded
    initiate_card_isle_widget();
    window.addEventListener("message", receiveMessage, false);
    function receiveMessage(event) {
                // verify that message came from Card Isle
      if (event.origin !== "https://www.cardisle.com")
        return;
      if (typeof event.data.status !== "undefined"){
        if (event.data.status == "success") {
          $(".card-isle-button").after("<img width=100 src='" + event.data.card_image + "' />");
          $(".card-isle-button").after("<p><b>Card name: </b>" + event.data.card_name + "</p>");
          $(".card-isle-button").after("<p><b>Card inside text: </b>" + event.data.card_text + "</p>");
          $(".card-isle-button").after("<p><b>Pickup code: </b>" + event.data.pickup_code + "</p>");
        }
      }
    }
  });
</script>
</body>
</html>

Details of the JSON message from the Card Isle iFrame:

RESPONSE PARAMETERS:
  status: "success" or "failure"
  pickup_code: unique 5-digit code that will be used to print the card
  card_image: url to a thumbnail of the card cover art
  card_text: peronalized message from inside of card
  artist_signature: signature of artist who created the cover art

EXAMPLE RESPONSE:
{
  "status": "success",
  "pickup_code": "123ab",
  "card_image": "https://urltoimage.jpg",
  "card_text": "Happy Earth Day!",
  "artist_signature": "Lyonel Feininger"
}

Additional features

There are two common scenarios that arise where the simple demonstration above will not suffice:

  1. Additional functionality to button with class card-isle-button
    Using initiate_card_isle_widget(useWrapper) with useWrapper equal to true will allow you to override the default functionality (a value of false will maintain the default functionality). Instead of the default functionality of opening the Card Isle iframe when the button with class card-isle-button is clicked, the shop_embed.js library will look for the function open_cardisle_iframe_wrapper (you must provide this function). Inside the open_cardisle_iframe_wrapper, you can call open_cardisle_iframe to open the iframe. In the demonstration below, the button with class card-isle-button is used initially to add a greeting card, and then to remove the card.

  2. Open iframe with a tag(s) pre-selected
    Instead of opening the Card Isle iframe with the default of no tags pre-selected, you can specify which tags you would like pre-selected. Using initiate_card_isle_widget(useWrapper, overrideSrc), you can specify a different collection of tags for the iframe. The tags must correspond to tags in the Card Isle library, and must be passed in URL percent encoding. For example, if you wished to pre-select "funny" and "thank you" tags, the value of overrideSrc would be https://www.cardisle.com/shop/#/selection?tags=funny,thank%20you. Note that you may call initiate_card_isle_widget() multiple times without any negative side effects. In the demonstration below, the select dropdown allows you to pre-select a variety of different tags.

The demonstration below includes both of these additional functionalities:

<html>
<head>
<style>
  img {
    width: 100px;
    display: block;
    border: solid 1px gray;
    margin: 10px 0;
  }
</style>
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<!-- import the Card Isle Javascript library -->
<script src="https://s3.amazonaws.com/cardisle.web/static/ecommerce/shop_embed.js"></script>
</head>
<body>
  <label>Select an occasion:
    <select>
      <option value="">----</option>
      <option value="birthday">Birthday</option>
      <option value="thank%20you">Thank You</option>
      <option value="birthday,funny">Birthday & Funny</option>
    </select>
  </label>
  <br>
  <br>
  <button type="button" class="card-isle-button">Add Greeting Card</button>
<script>
  function open_cardisle_iframe_wrapper() {
    if ($(".card-isle-button").text().indexOf("Remove") > -1) {
      remove_card();
    }
    else {
      open_cardisle_iframe();
    }
  }
  function remove_card() {
    $("img").remove();
    $("p").remove();
    $(".card-isle-button").text('Add Greeting Card');
  }
  $(document).ready(function() {
    // initiate Card Isle iframe with additional functionality for card-isle-button
    initiate_card_isle_widget(true);
    window.addEventListener("message", receiveMessage, false);
    function receiveMessage(event) {
      if (event.origin !== "https://www.cardisle.com")
        return;
      if (typeof event.data.status !== "undefined"){
        if (event.data.status == "success") {
          $(".card-isle-button").after("<img width=100 src='" + event.data.card_image + "' />");
          $(".card-isle-button").after("<p><b>Card name: </b>" + event.data.card_name + "</p>");
          $(".card-isle-button").after("<p><b>Card inside text: </b>" + event.data.card_text + "</p>");
          $(".card-isle-button").after("<p><b>Pickup code: </b>" + event.data.pickup_code + "</p>");
          $(".card-isle-button").text("Remove Greeting Card");
        }
      }
    }
  });
  $("select").on("change", function() {
    // calling initiate_card_isle_widget() additional times with different overrideSrc parameters simply updates the existing instance
    initiate_card_isle_widget(true, "https://www.cardisle.com/shop/#/selection?tags=" + this.value);
  });
</script>
</body>
</html>


Printing the cards is easy

We have a user-friendly interface for printing cards from your Card Isle printer, but if you would like an API integration into your platform, we offer that as well.

POST ENDPOINT: https://www.cardisle.com/api/partner/print

POST PARAMETERS:
  pickup_code: (REQUIRED) the same pickup_code that was created when the card was designed
  partner_uuid: (REQUIRED) your printer's unique identifier (provided by Card Isle)
  version: (REQUIRED) most recent version is 1
  testing: (OPTIONAL) boolean to test API

RATE LIMIT: 1 request/printer/second

EXAMPLE POST:
{
  "pickup_code": "123ab"
  "partner_uuid": "11111111-aaaa-bbbb-2222-cccccccccccc"
  "testing": true
  "version": "1"
}

RESPONSE PARAMETERS:
  status: "success" or "failure"
  message: if there is a failure, this will give a brief description of why

EXAMPLE RESPONSE:
{
  "status": "success",
  "message": "None"
}


Card Examples

Want to learn more?



Back