Guide

How to add a 3D product configurator to WooCommerce

, imagine.io ·

Paste one iframe tag into the product's description, or print it from a theme hook, and add your store's domain to the link's allowed domains in the imagine.io dashboard. The configurator loads on the product page with its own customisation options and live price, or with the panel hidden and your own buttons driving it. No plugin; the cart line takes a few lines of PHP in the child theme, shown below. For a page that is not a product, see the WordPress guide.

1 THE LINKimagine.io dashboardScenes › Configurable Systems› Sharing Links: add your domain,then Copy embed code2 PASTE ITWooCommerceProducts › edit the productDescription › Text tabpaste the iframe, update3 LIVEYour product page3D view, customisation options,live priceadd to cart through the bridgethe link carries its own catalog and theme; the page only frames it 1 THE LINKimagine.io dashboardScenes › Configurable Systems› Sharing Links: add your domain,then Copy embed code2 PASTE ITWooCommerceProducts › edit the productDescription › Text tabpaste the iframe, update3 LIVEYour product page3D view, customisation options,live priceadd to cart through the bridgethe link carries its own catalog and theme;the page only frames it
Where the embed goes: the link is made in the dashboard, pasted into the WooCommerce editor, and the configurator renders inside the page.
This guide uses the embed route. One iframe, a sharing link, and the bridge for the cart. Your own buttons are already covered: hide the configurator's panel and drive it from the page through the bridge (step 5 below). Want to change the configurator itself, the parts inside the frame? Build it with the SDK, host that page, and embed it with the same iframe: the bridge activates on any page that mounts the SDK inside an iframe, so everything below about the cart works unchanged. All three routes: which route fits which site.

The embed code

One element. The configurator boots, loads its catalog and renders itself, with its customisation options and live price. Replace lk_YOUR_LINK with your sharing link.

<iframe
  id="configurator"
  title="Product configurator"
  src="https://configurator.imagine.io/lk_YOUR_LINK"
  style="width:100%; height:640px; border:0; display:block"
  allow="xr-spatial-tracking; fullscreen; clipboard-write"
  referrerpolicy="strict-origin-when-cross-origin"
  loading="lazy"></iframe>

Step by step

  1. Create the sharing link and allow your domain

    In the imagine.io dashboard open Scenes › Configurable Systems, pick the system, and on its Sharing Links tab create a link. Give it a name for where it will live, choose a theme or leave the default, and under Allowed domains add every domain the page will be served from. Leave the list empty while you test locally, and fill it in before you go live: a link embedded on a domain that is not listed shows a “not authorized” card instead of the configurator.

    Copy embed code on the row gives you the iframe below with the link filled in.

    The Sharing Links tab of a system, with one link showing its name, theme and allowed domains
    Scenes › Configurable Systems › Sharing Links. One link per place you use it; the allowed domains are set here.
  2. Paste it into the product page

    Open the product under Products, switch the description editor to the Text (or Code) tab, and paste the iframe where the configurator should appear. Update the product.

    For every product of a line, a developer can instead print the iframe from a hook such as woocommerce_after_single_product_summary in the child theme, with each product's sharing link stored in a custom field, so no product description carries code.

  3. Keep the HTML intact

    Some security plugins and user roles strip iframes on save. If the tag disappears, save the product as an Administrator or Shop manager, or allow the iframe tag for the role that edits products. Caching and optimisation plugins that lazy-load iframes are fine; the configurator already loads lazily.

  4. Size it for the page

    The iframe takes the width of its container. Give it a height that fits the product layout, 640px is a good start, or 80vh for a full-page experience. On phones the configurator lays itself out for the narrow width.

  5. Decide who owns the customisation options

    Keep the configurator's panel, or hide it with ?hide=sidebar on the link and drive the scene from your own swatches through the postMessage bridge. The 3D view stays.

    https://configurator.imagine.io/lk_YOUR_LINK?hide=sidebar

    With the panel hidden, your page sends the choices in. Wait for the frame to say it is ready, read the option sets to build your own swatches from, then select by name or by id. The ten-line callConfigurator helper is the one from the cart section below.

    const iframe = document.getElementById('configurator');
    
    window.addEventListener('message', (e) => {
      if (e.data?.type === 'configurator:ready') start();          // the frame is listening
    });
    
    async function start() {
      // Every option set and option, to build your own swatches from
      const sets = await callConfigurator(iframe, 'getOptionSets');
    
      // Your swatch -> the configurator. By name, or by id when your CMS stores ids
      await callConfigurator(iframe, 'selectOption', { optionSet: 'Fabric', option: 'Cognac' });
      await callConfigurator(iframe, 'selectOption', { optionSetId: 41, optionId: 118 });
    
      // Hide or show parts of the configurator's interface after boot
      await callConfigurator(iframe, 'hideUI', { regions: ['sidebar'] });
    }

    What you can pass and what comes back: the URL parameters (hide, gui, theme, project, config), the full protocol, every command with its payload and its real reply (select options, read the quote and the state, camera, interface regions, undo and redo), the events the frame sends out, and the helper. One thing to know: a command the frame accepts can still be refused by a rule a moment later, which arrives as an evaluate.rejected event, so roll a cart line back on that event, not on the command's reply.

  6. Add every domain you serve from

    Add the live domain and any staging domain to the link's allowed domains. The check reads the referrer, so keep the iframe's referrerpolicy at strict-origin-when-cross-origin or looser.

  7. Test on the store

    Open the product on the live domain, change a few options and watch the price. Then wire the cart below.

Hand the configuration to your cart

The bridge gives the page the itemised quote, a thumbnail and a snapshot of the build. To get them onto the WooCommerce cart line: the JavaScript below posts them to a small endpoint, and a few lines of PHP in the child theme store them as cart item data so they travel onto the order.

<button id="add-to-cart" disabled>Add to cart</button>
// Ten lines you write once: posts a command into the iframe and resolves with its reply.
function callConfigurator(iframe, action, payload) {
  return new Promise((resolve, reject) => {
    const requestId = 'req-' + Math.random().toString(36).slice(2);
    const onReply = (e) => {
      const m = e.data;
      if (m?.type !== 'configurator:response' || m.requestId !== requestId) return;
      window.removeEventListener('message', onReply);
      m.success ? resolve(m.data) : reject(new Error(m.error));
    };
    window.addEventListener('message', onReply);
    iframe.contentWindow.postMessage({ action, payload, requestId }, '*');
  });
}
const iframe = document.getElementById('configurator');
const add = document.getElementById('add-to-cart');

window.addEventListener('message', (e) => {
  const m = e.data;
  if (m?.type === 'configurator:ready') add.disabled = false;
  // The price follows every change the shopper makes. No polling.
  if (m?.type === 'configurator:event' && m.event === 'price.changed') {
    add.textContent = `Add to cart: ${m.data.currency} ${m.data.grandTotal}`;
  }
});

add.onclick = async () => {
  const quote      = await callConfigurator(iframe, 'getQuote');          // itemised, priced by the engine
  const { dataUrl } = await callConfigurator(iframe, 'getScreenshot');    // thumbnail for the cart
  const snapshot   = await callConfigurator(iframe, 'getConfiguration');  // reopen the exact build later
  await fetch('/wp-json/mystore/v1/configured-cart', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'X-WP-Nonce': wpApiSettings.nonce },
    body: JSON.stringify({ product_id: WOO_PRODUCT_ID, quote, image: dataUrl, snapshot }),
  });
};
// functions.php (child theme): accept the post and add a cart line with the configuration attached
add_action('rest_api_init', function () {
  register_rest_route('mystore/v1', '/configured-cart', [
    'methods' => 'POST', 'permission_callback' => '__return_true',
    'callback' => function (WP_REST_Request $r) {
      $data = ['imagine_quote' => $r['quote'], 'imagine_snapshot' => $r['snapshot'], 'imagine_image' => $r['image']];
      $key = WC()->cart->add_to_cart((int) $r['product_id'], 1, 0, [], $data);
      return ['cart_item_key' => $key];
    },
  ]);
});
// Show the configuration on the cart and the order, and carry it onto the order line
add_filter('woocommerce_get_item_data', function ($item_data, $cart_item) {
  if (!empty($cart_item['imagine_quote'])) {
    $item_data[] = ['name' => 'Configuration', 'value' => $cart_item['imagine_quote']['system']['name']];
  }
  return $item_data;
}, 10, 2);
add_action('woocommerce_checkout_create_order_line_item', function ($item, $key, $values) {
  if (!empty($values['imagine_snapshot'])) $item->add_meta_data('_imagine_snapshot', wp_json_encode($values['imagine_snapshot']));
}, 10, 3);

The price the engine returns is in quote.totals.grandTotal. WooCommerce charges the product's own price unless you set it from the quote in a woocommerce_before_calculate_totals hook, which is the usual next step for configured products. The bridge chapter documents every field of the quote.

Frequently asked questions

Do I need a plugin?

No. The embed is one iframe in the product description or a theme hook, and the cart hand-off is a few lines of PHP in the child theme, shown above. Nothing is installed from a marketplace.

Can WooCommerce charge the engine's price?

Yes, with one more hook. WooCommerce charges the product's own price by default; set the cart item's price from quote.totals.grandTotal in a woocommerce_before_calculate_totals hook and the cart, the checkout and the order carry the engine's number.

My site has a Content-Security-Policy. What does it need?

Allow the configurator origin in frame-src, for example frame-src https://configurator.imagine.io. The configurator host permits framing by the domains in the link's allowed domains, so add your site there too.

Can I use my own swatches instead of the configurator's customisation options on WooCommerce?

Yes. Add ?hide=sidebar to the link so the panel disappears, then call selectOption from your page through the postMessage bridge. getOptionSets returns every option set and option to build your buttons from. The SDK docs cover each command.

Troubleshooting

The iframe disappears when I save the product.

WooCommerce runs on WordPress, which strips iframes for roles without the unfiltered_html capability: the content is sanitised on save and the iframe and script tags are removed. Some security plugins do the same for everyone. Save as an Administrator, or allow the iframe tag for the role that edits products. Which roles have it: WordPress's Roles and Capabilities page.

The page shows a “not authorized” card instead of the configurator.

The page's domain is not in the link's Allowed domains. Add it in Scenes › Configurable Systems › Sharing Links, including any preview or staging domain you test on. The check reads the referrer, so the iframe must not set referrerpolicy to no-referrer.

The configurator is blank, or the events arrive but every command times out.

Two usual causes. The page is opened from the file system rather than a web server: a file:// page has no origin the browser will deliver replies to. Or the iframe has a sandbox attribute that strips allow-scripts or allow-same-origin. Remove the sandbox attribute and serve the page over http.

Fullscreen or the Copy button does not work inside the embed.

The iframe needs allow="xr-spatial-tracking; fullscreen; clipboard-write". Without fullscreen the browser blocks the fullscreen toggle. Without clipboard-write in the iframe’s allow attribute, the browser blocks copying inside the configurator.

A licence notice appears on the real site but not in testing.

The free plan is for non-commercial evaluation with the imagine.io watermark. Running on your own domain and storefront is part of a paid plan; the plans are in the dashboard under Settings › Billing.

Other platforms

SDK documentation · Admin guide