Iframe Embed: How to Handle "Add to Cart" Actions

This guide shows how to connect Sign Customiser to the “Add to Cart” function on your own website. Your website must let you add an iframe and custom JavaScript. It is for the plain <iframe> embed. In this embed, you put an <iframe> tag on your page and you do not set up an integration. For a Universal customiser, this embed sends the onProductCreated message. Get the iframe code from Embed the customiser on any website.

Do you use a Custom API integration with the <sign-customiser-embed> code? That embed sends a different event, sc:product:created. Use Custom API Integration instead.

Example: the Finish button below the price in the customiser, when the customiser frame is 1025 px wide or more.

The customer clicks the button below the price when the customiser frame is 1025 px wide or more. With Quote Mode off and no enabled Etsy integration, the button label depends on the customiser. If the customiser has a review screen, the button shows Finish. Finish opens the review screen. On the review screen, the customer clicks Add to Bag. If the customiser has no review screen, the button shows Add to Bag at once. A customiser can use its own button labels. With Quote Mode on, or with an enabled Etsy integration, the button has a different label and the customiser does not send the message in this guide.

When the customer clicks Add to Bag, the customiser creates the product and sends a message to your page. Your page must add the product to its own cart. Your page must then send the result to the customiser.

Before you start

Your page must send a referrer to the iframe. The customiser uses the referrer to find the address of your page. If your page uses a no-referrer policy, the customiser cannot send the product to your page. The customer sees an add-to-cart error. Your page receives no message.

Step 1: Insert JavaScript Code

1. Add the attribute id="sign-customiser" to your <iframe>.

2. Insert this JavaScript code below your <iframe> on the same HTML page:

<script>
const customiser = document.getElementById("sign-customiser");
const customiserOrigin = "https://web.signcustomiser.com";

window.addEventListener("message", async (event) => {
  // Accept messages only from your customiser iframe.
  if (event.origin !== customiserOrigin) return;
  if (event.source !== customiser.contentWindow) return;
  if (event.data.type !== "onProductCreated") return;

  const { checkoutAttemptId, product } = event.data;
  let result = { outcome: "succeeded" };

  try {
    await addProductToCart(product);
  } catch (error) {
    result = { outcome: "failed", classification: "unknown_failure" };
  }

  customiser.contentWindow.postMessage(
    { type: "sc:cart:result", checkoutAttemptId, ...result },
    customiserOrigin
  );
});

async function addProductToCart(product) {
  // Custom logic to add event.data.product to your cart
}
</script>

The first two checks stop other frames on your page from sending a false product to your cart.

Step 2: Implement Custom Logic

Replace // Custom logic to add event.data.product to your cart with your own code. The code must add the product to your cart. If the cart refuses the product, the code must throw an error.

Do not trust the price in the message. Compare it with your own prices before you charge the customer.

Step 3: Send the Cart Result Back

The customiser waits up to 60 seconds for a reply to each message. The code in Step 1 sends the reply. The reply is an sc:cart:result message with these fields:

• checkoutAttemptId: Copy this value from the onProductCreated message.

• outcome: Use succeeded or failed.

• classification: Send this field only when the outcome is failed. Use platform_rejected, platform_rate_limited, platform_variant_missing, platform_unavailable, cart_unavailable, or unknown_failure.

Send the reply to the customiser iframe. Use https://web.signcustomiser.com as the target origin. If you do not send a reply, Sign Customiser records the attempt as unacknowledged.

Does your page go to the cart page after the product is added? If it does, wait first. When the customiser has queued your result, it sends an sc:cart:result:ack message. Wait for this message or for 400 milliseconds. Then go to the cart page. If you go sooner, the browser closes the iframe before the iframe sends the result.

Step 4: Understand the Product Data

When a customer adds a custom sign to the cart, the event.data.product object contains detailed product information, such as these sample values:

• text: “Hello World”

• font: Gruppo

• colour: Pink

Example Product Object:

This example is shortened. The real object contains more fields. The fields change with the sign type. The option names, values and the description text are sample values.

{
  "text": "Hello World",
  "textAlign": "left",
  "font": "Gruppo",
  "colour": "Pink",
  "size": "50cm",
  "support": "Cut to shape",
  "supportColour": "Clear Acrylic Transparent - Free",
  "extra": [
    { "name": "Mounting Options", "value": "Complimentary Silver Installation Kit" },
    { "name": "Dimmers & Remotes", "value": "Standard Dimmer (+3 USD)" }
  ],
  "price": "86.34",
  "sizeCm": "50cm X 5.59cm",
  "sizeIn": "19.69in X 2.2in",
  "description": "<p>Text: Hello World\nFont: Gruppo\nColour: Pink\nSize: 50cm\nDimmers &amp; Remotes: Standard Dimmer (+3 USD)</p>",
  "taxable": true,
  "productImage": "base64 encoded image",
  "productImageWhite": "base64 encoded image"
}

The description field is HTML. It has <p> elements, and it can also have <ul> lists. To show it as plain text, remove the tags and decode the HTML entities. For example, & becomes &.

Use this product object to create the product in your eCommerce backend. Then add the product to the shopping cart.