Shopify Custom Integration

The OV25 Shopify App is the fastest way to add configurators to a Shopify store, and it handles pricing, the cart, and checkout for you. But you do not have to use it.

This page shows a different approach: store a configurator link on each product using a metafield, then load that link in an iframe on your product template. You add a few lines of Liquid to your theme once. After that, giving any product a configurator is just pasting a link.

This approach suits you if:

• You want full control over how and where the configurator appears
• Your theme is heavily customised and the app's automatic setup does not fit it
• You want to take enquiries or quotes instead of standard Shopify orders

How it works

1. Each product gets a metafield that holds its configurator link
2. Your product template shows an iframe whenever that metafield is filled in
3. Products without the link keep their normal product page

Before you start

You need two things from the OV25 dashboard:

1. An API key. Create one at app.orbital.vision/auth/api-keys and choose the Product Configurator Access type.
2. Your store's domains authorised. Add both your .myshopify.com domain and your custom domain at app.orbital.vision/authorized-domains. The configurator will not load on a domain that is not on this list.

Step 1: Create the metafield

1. In Shopify Admin, go to Settings → Custom data → Products
2. Click Add definition
3. Name it OV25 configurator link
4. Set the namespace and key to custom.ov25_configurator_url
5. Set the type to URL
6. Save

Step 2: Add the link to each product

The link for a product looks like this:

https://configurator.orbital.vision/[API_KEY]/[PRODUCT_ID]

• [API_KEY] is your Product Configurator Access key
• [PRODUCT_ID] is the OV25 product ID, shown in the ID column at app.orbital.vision/products

Open the link in a browser tab first to check it works. The configurator should load and fill the page.

Then, on each product in Shopify Admin, scroll down to the Metafields section and paste the link into OV25 configurator link.

Step 3: Show the iframe on your product template

There are two ways to do this. Neither needs a developer for a basic setup.

Option A: Custom Liquid block on your existing template

1. Go to Online Store → Themes → Customize
2. Open your product template
3. Add a Custom Liquid block or section where you want the configurator to appear. Exactly where you can place it depends on your theme; near the product images is usually best.
4. Paste this in:

{%- assign ov25_url = product.metafields.custom.ov25_configurator_url.value -%}
{%- if ov25_url != blank -%}
  <div id="ov25-viewer" style="aspect-ratio: 4 / 3; width: 100%;">
    <iframe
      src="{{ ov25_url }}"
      title="Configure {{ product.title | escape }} in 3D"
      allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; xr-spatial-tracking; fullscreen"
      allowfullscreen
      style="width: 100%; height: 100%; border: 0;"
    ></iframe>
  </div>
{%- endif -%}

Products without the metafield show nothing here, so the block is safe on a template that normal products also use.

Option B: A separate product template

If you would rather keep configurator products on their own template:

1. In the theme editor, open the template picker at the top and choose Create template. Base it on your product template and name it something like ov25.
2. Add the Custom Liquid block from Option A to the new template.
3. On each configurator product in Shopify Admin, set Theme template (in the right-hand sidebar) to your new template.

Sizing

The iframe fills whatever container you put it in, so the container needs a size. The aspect-ratio: 4 / 3 in the snippet above is a good starting point: the viewer keeps a stable shape on desktop and mobile, and the page does not jump while it loads. Adjust the ratio, or give the container a fixed height, to suit your layout.

The allow attribute matters too. It grants the browser permissions the configurator needs for features like AR on mobile, so keep the full list from the snippet. Each permission is explained in the API reference.

Start on a specific colour or configuration

A plain product link opens the configurator with its default selections. Add a selections parameter to the link to start it on a specific configuration instead:

https://configurator.orbital.vision/[API_KEY]/[PRODUCT_ID]?selections=fabric~pearl~legs~dark-oak

The value is a list of option and selection names in pairs, joined with ~. The example above sets the Fabric option to Pearl and the Legs option to Dark Oak.

• Use the names you see in the configurator menus, in lower case, with hyphens instead of spaces
• Names do not need to be exact. The configurator picks the closest match, so fabric~pearl finds a fabric called Pearl even if its full name is longer
• A pair that matches nothing is ignored, and that option keeps its default

If the link loads more than one product, add productId= to say which product the selections belong to:

https://configurator.orbital.vision/[API_KEY]/6935-6936?productId=6935&selections=fabric~pearl

This is an ordinary link, so it works anywhere, not just in the metafield: in an email, in a blog post, or as a "shop this look" link under a lifestyle photo.

A different link on each variant

You can give each Shopify variant its own configurator link, so the configurator changes when the customer picks a different variant. This is useful when:

• Each variant is a different OV25 product. For example a Small / Medium / Large picker where each size is its own model.
• Each variant should start on a different colour. Give every colour variant the same product link with a different selections value, and picking a swatch jumps the configurator to that fabric.

For choices the configurator already handles on its own, you do not need variants at all. One link on the product is enough.

Add the metafield to variants

Variants have their own metafields, separate from the product's:

1. In Shopify Admin, go to Settings → Custom data → Variants
2. Click Add definition, name it OV25 configurator link, set the namespace and key to custom.ov25_configurator_url, and set the type to URL
3. On each variant, paste that variant's link (open the product, click the variant, and scroll down to its Metafields section)

Use the variant's link in the template

Change the first line of the snippet from Step 3 so it prefers the variant's link and falls back to the product's:

{%- assign ov25_url = product.selected_or_first_available_variant.metafields.custom.ov25_configurator_url.value
  | default: product.metafields.custom.ov25_configurator_url.value -%}

This covers the first page load, including links that arrive with ?variant= already in the address.

Swap the iframe when the variant changes

Shopify does not reload the page when the customer picks a variant, so a small script swaps the iframe. Add this below the iframe in the same Custom Liquid block:

<script type="application/json" id="ov25-variant-urls">
  {
    {%- for variant in product.variants -%}
      "{{ variant.id }}": {{ variant.metafields.custom.ov25_configurator_url.value | json }}{%- unless forloop.last -%},{%- endunless -%}
    {%- endfor -%}
  }
</script>
 
<script>
  (function () {
    var urls = JSON.parse(document.getElementById('ov25-variant-urls').textContent);
    var iframe = document.querySelector('#ov25-viewer iframe');
    if (!iframe) return;
 
    function swapToVariant() {
      var variantId = new URLSearchParams(window.location.search).get('variant');
      var url = urls[variantId];
      if (url && iframe.src !== url) iframe.src = url;
    }
 
    document.addEventListener('change', function () { setTimeout(swapToVariant, 200); });
    document.addEventListener('click', function () { setTimeout(swapToVariant, 200); });
  })();
</script>

How it works: the first script writes out a list of variant IDs and their links. The second waits for the customer to interact with the page, reads which variant the theme has put in the address bar (?variant=), and loads that variant's link if it is not already showing. Variants without a link are left alone.

Almost all modern themes update the address bar when a variant is picked; the short wait gives the theme time to do it. If yours does not, ask your theme developer to run the same swap wherever the theme reacts to variant changes.

What this approach does and does not do

The iframe is the complete configurator. The 3D view, the option menus, and the live price all appear inside it. But nothing inside the iframe is connected to Shopify:

• The configured price does not reach your Shopify cart or checkout. A standard Add to cart button still sells the product at its normal Shopify price.
• There are no automatic cart price updates, no configured cart thumbnails, and no swatch pages. Those come from the app.

So decide what buying looks like on these pages. The common choices:

1. Take enquiries instead of orders. Hide the Add to cart button on these products and add a quote or enquiry form. If the form includes a price, read it from the configurator messages described below.
2. Build your own cart handling. The configurator sends your page live messages with the current price, SKU, and selections. Your code can listen for these and run its own add to cart flow. The API reference documents every message.
3. Use the app instead. If you want pricing, the cart, and checkout handled for you, the OV25 Shopify App does all of this.

Optional: read the live price on your page

The configurator posts messages to the page it is embedded in. For example, to show the configured price somewhere outside the iframe:

<span id="my-price"></span>
 
<script>
  window.addEventListener('message', (event) => {
    if (event.origin !== 'https://configurator.orbital.vision') return;
 
    const message = event.data;
    if (!message || message.type !== 'CURRENT_PRICE') return;
 
    const price = JSON.parse(message.payload);
    document.querySelector('#my-price').textContent = price.formattedPrice;
  });
</script>

The same pattern gives you the SKU (CURRENT_SKU), the selected options (CONFIGURATOR_STATE), a shareable link for the current configuration (CURRENT_QUERY_STRING), and more. You can also send messages the other way, for example to change the product shown in the iframe without reloading it.

For a full walkthrough of a custom product page built this way, with product switching, external option buttons, galleries, and loading states, see Optimal Custom Integration.

Troubleshooting

The iframe is blank or shows an error. Open the metafield link directly in a new browser tab. If it does not load there, the API key or product ID is wrong. If it loads there but not on your store, your store's domain is missing from your authorised domains. Remember to add both the .myshopify.com domain and your custom domain.

The configurator has no height. The iframe fills its container, so the container must have a size of its own. Keep the aspect-ratio wrapper from the snippet, or give the container a height.

The configurator shows the wrong product. The iframe shows whatever the metafield link points at. Check the product ID in the link against app.orbital.vision/products.

The link does not start on the right colour. Check the names in the selections value against the option and selection names shown in the configurator menus. A pair that matches nothing is ignored, so a misspelt name quietly falls back to the default.