How to Embed a 3D Viewer, Configurator & Customizer with iframe + postMessage (Quick 5-Minute Setup)

Introduction

Want to add 3D/AR previews and real-time product personalization to your store without months of coding? You can — and it only takes a few minutes. By embedding a 3D Viewer, Configurator, or Customizer with a simple iframe and postMessage, you unlock interactive shopping experiences that boost conversion, shorten checkout, and reduce returns.

This guide walks you through a quick 5-minute setup. You’ll see how to paste ready-made snippets, adjust URL parameters, connect your cart via postMessage, and keep everything secure. Works on Shopify, WooCommerce, Webflow, Wix — or any headless stack.

Quick start: 5-minute checklist

1. Create a project in Alter Product.
2. Go to Share and set visibility to public for your chosen module (Viewer, Configurator, or Customizer).
3. Copy the generated iframe code.
4. Paste it on your page and tweak URL parameters (e.g., add_to_cart=1, bcg, env).
5. Add postMessage handlers for cart events and product data.
6. Whitelist your domain in E-commerce Settings → Integration for security.

Tip: Real-time pricing is available in all plans. White-label branding (logo/colors, nav bar) comes with Business, and creating your own customizers is unlocked with Business PRO.

Step 1: Embed with iframe

Each module has its own URL. Copy it from the Share tab and embed it where you need. Here are the basics:

Viewer (3D/AR preview)

<iframe src="https://alterproduct.com/app/viewer/40?add_to_cart=1&nav=1" width="100%" height="640" ></iframe>

Configurator (variants + live price)

<iframe src="https://alterproduct.com/app/configurator/41?add_to_cart=1" width="100%" height="720"></iframe>

Customizer (full personalization + print-ready)

<iframe src="https://alterproduct.com/app/customizer/44" width="100%" height="800"></iframe>

Note: nav=1 (your branded top bar) is available from Business. On mobile, AR works out of the box in the Viewer or configurator — no extra apps required.

Step 2: Styling & URL parameters

You can fine-tune the shopping experience in seconds by adding URL parameters to your iframe. Here are the most common ones:

• nav=0|1 — toggle the top navigation bar (available in Business/PRO).
• add_to_cart=0|1 — show or hide the “Add to Cart” button.
• bcg=value — set background (gradient, theme, or uploaded environment).
• env=1 — select HDRI environment lighting.
• light_intensity=0–2 — control light intensity (default ~0.6).

For full tables of supported parameters see the documentation:

• Viewer — styling & URL parameters
• Configurator — styling & URL parameters

Finally, don’t forget to style the iframe container with CSS (aspect ratio, rounded corners, spacing) so your 3D models look comfortable and immersive. Make sure it also matches the overall look & feel of your site — consistent styling reinforces your brand and keeps the experience seamless for shoppers.

Step 3: Integrate with postMessage (Viewer, Configurator, Customizer)

postMessage lets your page talk to the embedded module and vice versa. You can request current product data (variant, price, qty) or react when a shopper clicks Add to cart.

Note: Always validate event.origin to accept messages only from the trusted source.

Viewer — two-way messages

<iframe
  id="viewerWidget"
  src="https://alterproduct.com/app/viewer/1?add_to_cart=1&nav=1"
  title="Alter Product Viewer"
  width="100%"
  height="560"
  style="border:0;border-radius:12px;"
  loading="lazy"></iframe>

<script>
  const ALLOWED_ORIGIN = "https://alterproduct.com";
  const viewer = document.getElementById("viewerWidget");

  // Example: request a snapshot of current state
  function requestViewerData() {
    viewer.contentWindow.postMessage(
      { type: "ALTER_VIEWER_GET_PRODUCT_DATA" },
      ALLOWED_ORIGIN
    );
  }

  window.addEventListener("message", (event) => {
    if (event.origin !== ALLOWED_ORIGIN) return;
    const { type, payload } = event.data || {};

    if (type === "ALTER_VIEWER_ADD_TO_CART") {
      console.log("[Viewer] ADD_TO_CART", payload);
      // TODO: add to cart
    }
    if (type === "ALTER_VIEWER_DATA_RESPONSE") {
      console.log("[Viewer] DATA_RESPONSE", payload);
      // TODO: update price / variant UI
    }
  });
</script>

Configurator — two-way messages

<button id="getDataBtn">Get Configured Product</button>

<iframe
  id="configuratorWidget"
  src="https://alterproduct.com/app/configurator/1?nav=0&add_to_cart=1"
  title="Alter Product Configurator"
  width="100%"
  height="600"
  ></iframe>

<script>
  const ALLOWED_ORIGIN = "https://alterproduct.com";
  const iframe = document.getElementById("configuratorWidget");

  // Ask iframe for current product data
  document.getElementById("getDataBtn").addEventListener("click", () => {
    iframe.contentWindow.postMessage(
      { type: "ALTER_CONFIGURATOR_GET_PRODUCT_DATA" },
      ALLOWED_ORIGIN
    );
  });

  // Listen to responses and Add to Cart
  window.addEventListener("message", (event) => {
    if (event.origin !== ALLOWED_ORIGIN) return;
    const { type, payload } = event.data || {};

    if (type === "ALTER_CONFIGURATOR_ADD_TO_CART") {
      console.log("[Configurator] ADD_TO_CART", payload);
      // TODO: add item to your cart
    }
    if (type === "ALTER_CONFIGURATOR_DATA_RESPONSE") {
      console.log("[Configurator] DATA_RESPONSE", payload);
      // TODO: show summary / sync price & variant
    }
  });
</script>

Customizer — order-first flow

In the Customizer, clicking Add to cart creates an order with status pending (customers can still edit via a secure link). You’ll receive the order data in the payload; after payment, switch status to lock editing.

<iframe
  id="customizerWidget"
  src="https://alterproduct.com/app/customizer/1?add_to_cart=1"
  title="Alter Product Customizer"
  width="100%"
  height="720"
  style="border:0;border-radius:12px;"
  loading="lazy"></iframe>

<script>
  const ALLOWED_ORIGIN = "https://alterproduct.com";

  window.addEventListener("message", (event) => {
    if (event.origin !== ALLOWED_ORIGIN) return;
    const { type, payload } = event.data || {};

    if (type === "ALTER_CUSTOMIZER_ADD_TO_CART") {
      console.log("[Customizer] ADD_TO_CART", payload);
      // Tip: payload includes the created "pending" order
      // 1) store orderId  2) redirect to checkout
      // (Optional) use API to fetch/update order later
    }
  });
</script>

Docs: detailed message lists & payloads:

• Viewer — postMessage
• Configurator — postMessage
• Customizer — postMessage

Tip: Always whitelist your domain in Storefront Settings → Integration and avoid using * as the target origin in production.

What you get: A snapshot of the current configuration — variant, price, quantity, metadata — ready to sync with your cart or summary.

Step 4: Add to Cart flows

• Viewer/Configurator: ALTER_*_ADD_TO_CART sends product data when users click the button. Just add it to your cart.
• Customizer: ALTER_CUSTOMIZER_ADD_TO_CART fires after the order is saved with pending status. This is the moment to:
  • store the order ID,
  • redirect to checkout,
  • (optional) fetch order details via API and lock editing once status changes.

Step 5: Security & compliance

• Whitelist your embedding domain in E-commerce Settings Integration section.
• Always filter event.origin (never use * in production).
• White-label options (logo, colors, branded nav) are in Business.

Step 6: Test & debug

• Open DevTools → Console to monitor postMessage logs.
• Test variant changes (Configurator) and Add to Cart flows.
• On mobile, test AR with the Viewer.
• If nothing shows — check public visibility and domain whitelisting.

Optional: Customizer API

For deeper workflows, connect the Customizer with Alter Product’s API. Typical use cases:

• fetch an order by ID,
• update status after payment,
• sync quantities,
• clean abandoned orders.

This ensures a smooth pipeline: design → cart → payment → production with print-ready exports.

Common mistakes (to avoid)

• No public visibility — iframe shows nothing.
• No event.origin filter — opens security risks.
• Domain not whitelisted in settings — messages fail.
• Iframe too small — cramped 3D view (increase height, add radius).
• Forgot add_to_cart=1 — button doesn’t appear.

See it live

FAQ

Can I embed on any CMS/site?

Yes — it’s just an iframe, compatible with any CMS or custom stack.

Is real-time pricing included in every plan?

Yes — it updates instantly across all plans.

Do I need a developer?

No — for basic embedding. For cart integration with postMessage or API, low-code is enough.

Does the Customizer generate print-ready files?

Yes — the Customizer can export print-ready files, available starting from the Personal plan.

Can I use my own logo and colors?

Yes — white-label is available from Business and higher.