Add an embedded iJewel viewer to Shopify

This guide adds an iJewel3D viewer to a Shopify product page with an iframe. Each product stores its own iJewel embed URL in a Shopify metafield, and the theme renders the viewer only when that URL is present.

This is the simplest Shopify option because the viewer remains self-contained. Use the Mini Viewer SDK integration instead when Shopify variants or custom page controls must interact directly with the viewer.

Before you begin

You need:

• Access to Shopify products, settings, and theme code
• An embed URL for each model from iJewel Drive or iJewel Design
• A duplicate theme for development and testing

If you do not have an embed URL yet, follow Create an iJewel Viewer Embed. Shopify needs only the URL from the generated iframe's src attribute, not the complete iframe code.

Step 1: Duplicate the Shopify theme

In Shopify admin, open Online Store → Themes, open the current theme's actions menu, and select Duplicate. Make and test the changes in the duplicate before publishing it.

Step 2: Create a product metafield

1. Open Settings → Custom data → Products. In some Shopify admin versions, this appears as Settings → Metafields and metaobjects → Products.

2. Select Add definition.

3. Enter the following values:

   • Name: iJewel viewer URL
   • Namespace and key: custom.model_source_embed
   • Description: Embed URL generated by iJewel Drive or iJewel Design
   • Type: URL
   • Values: One value

4. Save the definition.

Select Products because every product can use a different viewer URL.

The display name can differ from this older screenshot; keep the documented namespace and key so the Liquid example works.

Step 3: Assign a viewer URL to a product

1. Open Products in Shopify admin and select a product.
2. Scroll to Metafields.
3. Paste the iJewel embed URL into iJewel viewer URL.
4. Save the product.

Paste the generated embed URL, not the full iframe code.

Repeat this step for every product that should display a 3D viewer. Products without a value will keep their normal layout.

Step 4: Add the iframe to the product template

In Shopify admin, open Online Store → Themes, open the duplicate theme's actions menu, and select Edit code. Open sections/main-product.liquid and add this block where the viewer should appear:

{%- assign ijewel_viewer_url = product.metafields.custom.model_source_embed.value -%}

{%- if ijewel_viewer_url != blank -%}
  <div
    class="page-width"
    style="margin-top: 2rem;"
  >
    <iframe
      src="{{ ijewel_viewer_url | escape }}"
      title="{{ product.title | escape }} — interactive 3D viewer"
      loading="lazy"
      allow="autoplay; fullscreen; xr-spatial-tracking; web-share"
      allowfullscreen
      style="width: 100%; min-height: 420px; aspect-ratio: 4 / 3; border: 0;"
    ></iframe>
  </div>
{%- endif -%}

The conditional prevents an empty iframe from appearing on products that do not have an iJewel URL.

Theme differences

Dawn-based themes are often customized. If sections/main-product.liquid does not exist, search the theme for the section that renders the main product media or product information. Place the block where it best fits that layout.

Step 5: Preview and test

Preview the duplicate theme and check:

1. A product with an iJewel URL displays the correct model.
2. A product without an iJewel URL does not show an empty space.
3. The viewer has enough height on desktop and mobile.
4. Fullscreen and viewer controls work as expected.
5. The storefront console has no blocked-frame or URL errors.

Troubleshooting

• The viewer is blank: open the metafield URL in a private browser window and confirm that the model is publicly accessible.
• The editor appears instead of the viewer: regenerate the embed and copy the iframe src, not the browser's editor URL.
• Shopify rejects the metafield value: confirm that you copied the complete https:// URL without quotation marks.
• The viewer is too short or too tall: adjust min-height and aspect-ratio in the iframe style.
• You need Shopify variants to change materials or models: use the Mini Viewer SDK integration.

Next steps

• Customize initial material selections
• Move to the Mini Viewer SDK for direct page-to-viewer interaction

Contact

For Shopify integration or licensing assistance, email contact@ijewel3d.com.