Embed API

Embed the 3D configurator on your storefront and drive it from your own UI.

There are two ways to use the configurator:

1. Shopify theme block (no code) — add the Jewelry Configurator block to your product template and set the options in the theme editor. Section 1 below.
2. Direct iframe (developers) — embed the iframe yourself and drive it from your own buttons via postMessage. Sections 2 onwards.

1. Shopify — each product's own model

Add the Jewelry Configurator block to your product template once. It then appears on every product page and works out which model belongs to the product the shopper is looking at, in this order — first hit wins:

1. The jewelshop.model metafield — a product metafield holding the URL of a .glb. Always wins, and it is what we fill in for you when we produce your models.
2. The product's own 3D model — a .glb you uploaded to the product in the Shopify admin (Products → your product → Add media). Nothing to configure at all.
3. The sample ring — a product with neither keeps showing the demo ring chosen in the block settings, so a half-finished catalog never renders an empty box.

To add the metafield: Settings → Custom data → Products → Add definition, namespace and key jewelshop.model, type URL (single-line text also works). Then fill it in per product.

The block renders the viewer chromeless — 3D only, no buttons of ours. Your product page already has the shopper's option pickers between the title and the price; a second set of controls inside the frame would drive nothing purchasable. To make the viewer react to those pickers, drive it over postMessage — section 3.

Part info on click. The block setting Show part info on click lets shoppers click or tap a stone or the band and see a small card with its name and your notes. The parts and notes come from the parts list in the jewelshop.model_roles metafield (section 4). To show your own design instead — photos, video, your fonts — leave the setting off and add a theme script that turns picking on and draws the note (section 4, option B).

Ring try-on. The block setting Show ring try-on adds a Try on button over the viewer: shoppers photograph the back of their hand (or upload a photo) and see the ring on their finger. It adds &tryon=1 and allow="camera" to the iframe. The photo is processed in the shopper's browser and never uploaded — not to us, not to the store (section 8).

Two-tone. Split the metal into parts in the same metafield (say head and band) and a theme script can give each its own metal when the shopper picks a two-tone option (section 5).

2. Embedding the iframe

<iframe
  src="https://jewelshop.ai/demo/?embed=1"
  width="100%"
  height="550"
  style="border:none;"
  allowfullscreen></iframe>

URL parameters

By default the embed is chromeless — just the rotating 3D viewer. Add &controls=1 only if you want our built-in switcher instead of your own UI.

Embedded on a site of yours, the loading screen shows only the progress bar, with no text or logo, whatever bg is. loader=0 hides the screen altogether.

Showing your own model

https://jewelshop.ai/demo/?embed=1&model=https://cdn.example.com/rings/solitaire.glb

Percent-encode the model value when you build the URL, so a ?, & or # in your model's own URL stays part of it (the example above has none):

const src = 'https://jewelshop.ai/demo/?embed=1&model=' + encodeURIComponent(modelUrl);

model is read only together with embed=1, and only while a page frames the viewer: opened in a tab of its own, the viewer ignores it. The URL must be https (or a path on jewelshop.ai itself), the file a .glb, or a .gltf whose buffers are embedded as data URIs (a buffer in a side file is refused), of at most 32 MiB (a larger file is cancelled mid-download), and the host must send CORS headers allowing jewelshop.ai to fetch it. You hear how the load went the same way as after set-model: model-loaded, or model-error and an empty viewer. A URL that isn't https (or ours) gets model-error {reason:'invalid-url'} without a download, and the viewer stays empty too.

Compressed models load faster, and we recommend them: meshopt compression and quantized geometry, which is what glTF Transform and gltfpack produce. Draco compression (Blender's “Compression” export option) is not supported yet, so export without it.

Your model is rendered with the materials you authored. We only take over a material when a role manifest tells us to: a small JSON file served next to the model, at the model's URL with .roles.json appended (solitaire.glb → solitaire.glb.roles.json):

{ "gem_nodes": ["Diamond_Round"], "metal_nodes": "*" }

• gem_nodes — nodes rendered as gemstones, with ray-traced refraction.
• metal_nodes — nodes whose colour follows the metal setting; "*" means every remaining material.
• parts (optional) — the parts shoppers can click, with your notes for each. See section 4.

No manifest means no recolouring — the piece is shown exactly as exported, which is what you want for a fixed showcase. Add one when the shopper should be able to change the stone or the metal.

When you can't serve a sidecar (&roles=)

A sidecar only works if you can put a file next to the model. When the model lives somewhere you don't control the paths — Shopify 3D media, served from the store's own domain, is the common case — pass the same JSON inline on the URL instead, URL-encoded:

…&model=https%3A%2F%2Fyour-store.myshopify.com%2Fcdn%2Fshop%2F3d%2Fmodels%2F…%2Fsolitaire.glb&roles=%7B%22gem_nodes%22%3A%5B%22Diamond_Round%22%5D%2C%22metal_nodes%22%3A%22*%22%7D

roles takes precedence over the sidecar: if it is present the viewer uses it and never fetches .roles.json. Omit it and the sidecar lookup happens as usual. A roles that isn't JSON of the manifest's shape (the same check as set-model's) is ignored with a console warning, and the sidecar is looked up instead. roles counts only next to an accepted model: it never applies to our demo rings. This is the URL twin of the set-model message's inline roles (below), and it is how a Shopify store keeps both the model and its roles entirely on Shopify — the roles ride along from a jewelshop.model_roles product metafield that the theme block forwards here automatically.

The whole iframe URL may be at most 32 KB; a longer one is refused with 414 URI Too Long before the viewer loads. URL-encoding inflates JSON (every quote, brace and colon becomes three characters), so a manifest with long part notes (parts[].data) can get there — keep the notes short, serve a sidecar, or send the manifest with set-model instead.

3. Driving it from your own UI (postMessage)

Every message — both directions — carries source: "jewelshop". Ignore any message without it.

Handshake — wait for ready

The viewer posts ready as soon as it is listening, and again once the 3D renderer has finished loading. Wait for it before sending commands.

const frame = document.querySelector('iframe').contentWindow;

window.addEventListener('message', (e) => {
  if (e.data?.source !== 'jewelshop') return;
  if (e.data.kind === 'ready' && e.data.rendererLoaded) {
    // Safe to send commands now.
  }
});

Commands you send (host → viewer)

A command that can't apply gets no reply rather than a misleading one, with these exceptions: set-model answers a URL it refuses with model-error, and set-part-material, set-variant, set-ring-size and get-dimensions always answer (section 5). Send commands after ready with rendererLoaded: true.

frame.postMessage(
  { source: 'jewelshop', kind: 'apply-preset', preset: { gem: 'ruby', metal: 'gold' } },
  'https://jewelshop.ai'   // the configurator's origin, so nothing else receives it
);

Passing the role manifest inline

set-model takes an optional roles object — the same manifest that would otherwise be served as <model>.glb.roles.json:

frame.postMessage({
  source: 'jewelshop',
  kind: 'set-model',
  url: 'https://cdn.example.com/rings/solitaire.glb',
  roles: { gem_nodes: ['Diamond_Round'], metal_nodes: ['Band'] }
}, 'https://jewelshop.ai');

Use this when the model sits somewhere you cannot add files next to it — an S3 bucket, a CDN, Shopify media — while the node roles live in your own database. Nothing is fetched; the manifest goes straight to the renderer.

• omitted — the viewer fetches the sidecar next to the model. The normal case.
• an object — used verbatim, no fetch.
• null — no roles at all; don't even look for a sidecar. The model renders exactly as authored.

Anything else — a string, an array, an object whose gem_nodes isn't a list of names or whose metal_nodes isn't "*" or a list, or a list of more than 1000 names or with a name over 256 characters — is refused with model-error {reason:'invalid-roles'} rather than being coerced into something that might repaint the piece. And because loads are deduplicated by URL, the roles that arrive with the first load of a given URL are the ones that apply.

Events you receive (viewer → host)

4. Part info on click and hover

Let shoppers click a stone to read about it, or hover the band to see the alloy — and show whatever you like when they do: a description, a photo, a video, a link. It is off in an embed until you turn it on.

Name the parts

Parts come from a parts list in the model's role manifest — the same JSON as above (the .roles.json sidecar, &roles=, or on Shopify the jewelshop.model_roles product metafield):

{
  "gem_nodes": ["Diamond_Cushion_Square", "diamond_side_001", "diamond_side_002"],
  "metal_nodes": "*",
  "parts": [
    { "id": "center-stone", "nodes": ["Diamond_Cushion_Square"], "label": "Center stone",
      "data": { "description": "1.2 ct cushion cut", "video": "https://…/stone.mp4" } },
    { "id": "side-stones", "nodes": ["diamond_side_*"], "label": "Side stones" },
    { "id": "band", "nodes": "metal", "label": "Band",
      "data": { "notes": ["14k gold", "lifetime warranty"] } }
  ]
}

• id is what the events report; label is optional.
• nodes lists node names (a trailing * matches a prefix), or one of "gems", "metal", "*".
• data is yours: any JSON, passed to you verbatim.

Without parts, each node in gem_nodes is its own part (named after the node) and the metal is one part, metal.

Option A: our built-in card (no code)

Add &picking=1 (on Shopify: the block setting Show part info on click). Hovering a part shows a small card with its label plus data.description and data.notes; clicking pins it; rotating or zooming closes it.

Option B: your own note (any HTML)

Turn picking on without our card and draw the note on your page. It is your DOM, so it can hold anything — a video included — and use your fonts. Each event carries:

{
  source: 'jewelshop', kind: 'part-click',
  part: { id: 'band', label: 'Band', role: 'metal', node: 'Ring', nodeRole: 'metal',
          model: 'https://…/piece.glb', data: { /* manifest data, verbatim */ } } | null,
  anchor:  { x, y } | null,  // the part's centre
  bounds:  { left, top, right, bottom } | null,  // the part's on-screen box
  pointer: { x, y } | null,  // where the pointer was
  pointerType: 'mouse' | 'pen' | 'touch'
}

anchor, bounds and pointer are CSS pixels inside the iframe; add the iframe's getBoundingClientRect() to place something on your page. Place a note just outside bounds (e.g. at bounds.right) so it doesn't cover the stone.

const frame = document.querySelector('iframe#jewel');
const send = (msg) => frame.contentWindow.postMessage({ source: 'jewelshop', ...msg }, 'https://jewelshop.ai');

window.addEventListener('message', (e) => {
  if (e.source !== frame.contentWindow || e.data?.source !== 'jewelshop') return;
  const { kind, part, pointer } = e.data;
  if (kind === 'ready' && e.data.rendererLoaded) send({ kind: 'set-picking', enabled: true, card: false });
  if (kind === 'part-click' && part) {
    const r = frame.getBoundingClientRect();
    showNote(part, r.left + pointer.x, r.top + pointer.y); // your UI, e.g. a <template> per part.id
  }
  if (kind === 'part-dismiss' || (kind === 'part-click' && !part)) hideNote();
});
// your note's close button: hideNote(); send({ kind: 'select-part', id: null });

Good to know

• Touch screens have no hover. On phones only a tap fires part-click, and a drag or pinch is never a tap. Put anything essential behind a click, not hover alone; a bottom sheet reads better than a note next to the finger.
• Hover waits for the pointer to rest (hoverDelay, 200 ms), so sweeping across the piece doesn't flash a note through every part. The part then fades in a soft highlight; the pointer cursor changes immediately.
• Cost: nothing while it is off. On, the viewer does a small extra pass once each time the picture settles — never while it rotates.

5. Two-tone: a different metal per part

Give one part of the piece its own metal: white-gold prongs on a yellow-gold band, a rose-gold setting, a sapphire centre stone among diamonds. The parts are the same parts list as in section 4, so first split the metal into the zones you want to colour separately:

"parts": [
  { "id": "head", "nodes": ["Prong_1", "Prong_2", "Prong_3", "Prong_4", "Basket"], "label": "Setting" },
  { "id": "band", "nodes": "metal", "label": "Band" }
]

"metal" gives the band every metal node the setting didn't claim. Order matters: each node goes to the first part that lists it, so list the setting before the catch-all. The other way round, the band takes every metal node, head gets none, and a material for head is accepted but changes nothing. Then:

send({ kind: 'apply-preset', preset: { metal: 'gold' } });   // the piece's metal
send({ kind: 'set-part-material', id: 'head',
       material: { color: [0.47, 0.47, 0.47] } });           // white-gold setting
send({ kind: 'set-part-material', id: 'head', material: null }); // back to the piece's metal

• material is { color?, roughness?, metalness?, ior?, dispersion?, softness?, axisColor?, axis?, haze?, inclusions? }. color is linear RGB, the same numbers our apply-preset metals use: silver (also our white gold) [0.47, 0.47, 0.47], gold [0.984, 0.541, 0.176], rose_gold [0.729, 0.419, 0.212]. roughness and metalness are 0–1 (metal defaults: 0.08 and 0.97). Leave a field out to keep the part's usual value. Each command replaces the part's previous one; null (or {}) clears it.
• A part with its own metal keeps it when you change the piece's metal with apply-preset: the fields you set stay, and a field you left out follows the piece. Cleared, it follows the piece again.
• Parts your manifest does not list as metal keep the materials from your file (enamel, leather, a painted accent). A command on them tints that material, textures included, and null restores it exactly.
• On a stone part, color is the stone's body colour: deeper where light travels further through the stone, its reflections white. ior (refractive index, 1–3) and dispersion (0–0.1) are its optics, as gemmology quotes them: quartz (citrine, amethyst) 1.54 / 0.013, tourmaline 1.63 / 0.017, sapphire 1.76 / 0.018. softness (0–1.5) is how soft the light the stone mirrors is: 0 keeps a diamond's crisp glints, about 0.65 gives a coloured stone the calm, broad highlights of a product photo, and past 1 neighbouring facets mirror much the same light and merge. haze and inclusions (0–1 each) scatter light inside the stone: haze an even milkiness that blends its facets (apatite, a commercial emerald), inclusions cloudy patches fixed in the stone that turn with it (an emerald's garden). Around 0.1–0.3 reads as a real stone; 0.6 and up goes opaque. axisColor (linear RGB) is pleochroism: the stone's colour looking down its optic axis, color being the one across it; light in between blends the two. A tourmaline is much darker down its axis, a tanzanite bluer. axis is which way that axis runs: 'length' (the default, along the stone) or 'table' (straight down through it). Without them a stone renders as a diamond. A stone shows its own setting through its underside, as a real one does: the viewer renders what surrounds each stone, the metal of your piece in its colours, and needs nothing from you for it. Keep your stones as data, a species table plus which stone is which, and send each stone its row:

  send({ kind: 'set-part-material', id: 'centre',
         material: { color: [0.25, 0.55, 0.7], ior: 1.635, dispersion: 0.013, softness: 0.65 } }); // apatite

• Changes fade in like the preset swatches. When a model loads (or reloads after the graphics context was lost), the materials it remembers show at once.
• Without model the command applies to the model on screen. To prepare a model that is still loading, pass model: '<the set-model url>'; it applies when the model arrives. The reply then has pending: true: the material is accepted, and a part that model turns out not to have is dropped when it loads, with no further message. If the load fails, that set-model's model-error is the answer and the material never shows. A model that is neither loaded nor loading (a typo, a load that already failed, a URL you never sent with set-model) is refused with model-not-loaded, so send set-model first. Each model remembers its own parts' materials.
• part-material-error reason: unknown-part (no such id in this model's manifest), invalid-material (an unknown key such as colour, or a value out of range), no-model (nothing loaded yet; wait for ready with rendererLoaded: true, or pass model), model-not-loaded (model is neither loaded nor loading), invalid-args (id not a string, no material field or an undefined one, or a bad model URL), viewer-unavailable (the viewer could not start, e.g. the configurator isn't licensed for your site or the browser has no WebGL 2; every command after it gets the same), apply-failed (the viewer could not apply it for another reason; message says why).

Interchangeable parts (variants)

A model can also carry alternatives for a part of the piece — a halo or none, a solitaire or a three-stone row, two head styles — all in the one .glb, laid out in place. List them in the manifest's slots:

"slots": [
  { "id": "halo", "label": "Halo", "default": "on",
    "variants": [
      { "id": "on",  "label": "With halo", "nodes": ["Halo_Stone_*", "Halo_Frame"] },
      { "id": "off", "label": "No halo",   "nodes": [] }
    ] }
]

send({ kind: 'set-variant', slot: 'halo', variant: 'off' });

• Exactly one variant of each slot is shown. nodes takes node names and prefix* patterns; a group name brings its whole subtree. A variant with no nodes shows nothing.
• The piece keeps its size and place when you switch, and its shadow follows. Make the band the lowest point of every variant.
• Part materials keep applying: a head part listing every head's nodes recolours whichever head is showing.
• model works as for set-part-material: without it the command applies to the model on screen; with the URL of a model still loading, the reply has pending: true and the variant shows when the model arrives (a slot or variant it turns out not to have is dropped then, with no further message). A model neither loaded nor loading is refused with model-not-loaded. Each model remembers its own choices, also when it reloads after the graphics context was lost.
• variant-error reason: unknown-slot (no such slot in this model's manifest), unknown-variant (the slot has no such variant), no-model (nothing loaded yet; wait for ready with rendererLoaded: true, or pass model), model-not-loaded (model is neither loaded nor loading), invalid-args (slot / variant not strings, or a bad model URL), viewer-unavailable (the viewer could not start; every command after it gets the same), apply-failed (the viewer could not apply it for another reason; message says why).

Size in millimetres

Once a model is measured (node tools/measure_ring.mjs ring.glb --size "US 7", see docs/model_format.md), the viewer knows its real size and hands it to your page — for the spec block next to the viewer:

send({ kind: 'get-dimensions' });
// → { kind: 'dimensions', model: null, dimensions: {
//      innerDiameterMm: 17.32, madeAtMm: 17.32, resizable: true,
//      bandWidthMm: 2.1, bandThicknessMm: 1.6,
//      ringSize: { mm: 17.5, EU: 54, US: 7, UK: 'N½' },
//      stones: [ { part: 'center-stone', count: 1, sizeMm: [6.5, 6.5, 3.9] } ] } }

model-loaded carries the same object. get-dimensions always answers: dimensions is null for a model nobody measured, or one not loaded (yet) — a .glb has no trustworthy scale of its own. A malformed model URL is not taken for an unmeasured model: it gets dimensions-error with reason: 'invalid-args' and model exactly as you sent it. Its other reasons are viewer-unavailable (the viewer could not start) and read-failed (message says why).

Show the piece in the shopper's size — the band changes, the stones and the head keep their real size, so a small size makes the stone look as big as it will on the finger:

send({ kind: 'set-ring-size', size: 'US 6' });   // or 'US 6½', 'EU 52', 'UK L½', '16.5 mm', 16.5, { system: 'us', value: 6 }
// → { kind: 'ring-size-set', size: 'US 6', model: null, pending: false,
//      dimensions: { innerDiameterMm: 16.51, madeAtMm: 17.32, resizable: true, … } }

• innerDiameterMm and ringSize follow the size shown; madeAtMm is the size the model was made in. resizable: false means the viewer could not use the model's measurements: it is shown as made, and set-ring-size is refused with not-calibrated.
• model works as for set-variant: without it the command applies to the model on screen; with the URL of a model still loading, the reply has pending: true and dimensions: null, and the size applies when the model arrives (dropped then, with no further message, if the model turns out not to be measured). A model neither loaded nor loading is refused with model-not-loaded. Each model remembers its size, also when it reloads after the graphics context was lost.
• ring-size-error reason: invalid-size (not a ring size, or outside 8–32 mm inner diameter), not-calibrated (the model was never measured, or its measurements can't be used), no-model (nothing loaded yet; wait for ready with rendererLoaded: true, or pass model), model-not-loaded (model is neither loaded nor loading), invalid-args (size not a number, a string or { system, value }, or a bad model URL), viewer-unavailable (the viewer could not start; every command after it gets the same), apply-failed (the viewer could not apply it for another reason; message says why).
• A stone's sizeMm is [length, width, depth] on its own axes: a round stone's diameter is the first. With picking on, the built-in part card shows a stone's size too.

Poses: upside down, on its side

Show the piece lying another way on the floor: default (as the model was made), upside-down (a half turn: a ring's head at the bottom) or side (a quarter turn: a ring standing up lies flat; one made lying down stands up on its band). The turn is about the horizontal axis the piece is longest along, and the piece is set down on the floor again with its shadow under it.

send({ kind: 'set-pose', pose: 'side' });
// → { kind: 'pose-set', pose: 'side', model: null, pending: false }
send({ kind: 'set-pose', pose: 'default', duration: 0 }); // at once

• It takes duration seconds, 0 to 5 (default 0.8): the piece lifts off, turns in the air and lands, its shadow fading out and in. 0 lays it there at once; so does a shopper's reduced-motion setting. A new set-pose while it turns changes its course from where it is; a ring size, a variant or try-on lands it first.
• The camera moves along with the piece to where it lands, keeping the shopper's angle and distance. Pass frame: false to move it yourself (set-camera).
• model works as for set-variant. Each model remembers its pose, also when it reloads after the graphics context was lost. A resized ring keeps its size.
• Try-on shows the ring as made: the piece is laid as made while try-on is open, and back in its pose after.
• pose-error reason: invalid-args (pose not one of the three, frame not a boolean, duration not 0 to 5, or a bad model URL), no-model, model-not-loaded, viewer-unavailable, apply-failed, as for set-ring-size.

6. Fullscreen

The iframe already allows fullscreen. Wrap it and fullscreen the wrapper so your own buttons stay on top:

<div id="jc-wrap" style="position:relative">
  <iframe id="jc" src="https://jewelshop.ai/demo/?embed=1" allowfullscreen></iframe>
  <button style="position:absolute;top:12px;right:12px"
          onclick="document.getElementById('jc-wrap').requestFullscreen()">
    Fullscreen
  </button>
</div>

7. Example — "View in 3D" over a photo gallery

Show product photos; the 3D viewer loads hidden and is paused once it is ready, so it uses no GPU until the shopper asks for it. On click, swap it in and resume.

<div id="gallery"><!-- your photos --></div>
<iframe id="jc" src="https://jewelshop.ai/demo/?embed=1"
        style="display:none" allowfullscreen></iframe>
<button id="view3d">View in 3D</button>

<script>
  const ORIGIN = 'https://jewelshop.ai';
  const frame = document.getElementById('jc');
  const send = (kind, extra = {}) =>
    frame.contentWindow.postMessage({ source: 'jewelshop', kind, ...extra }, ORIGIN);

  let ready = false;
  window.addEventListener('message', (e) => {
    if (e.origin !== ORIGIN || e.data?.source !== 'jewelshop') return;
    if (e.data.kind === 'ready' && e.data.rendererLoaded) {
      ready = true;
      if (frame.style.display === 'none') send('pause');   // hidden: park it
    }
  });

  document.getElementById('view3d').onclick = () => {
    document.getElementById('gallery').style.display = 'none';
    frame.style.display = 'block';
    if (ready) send('resume');   // not ready yet: it starts running anyway
  };

  // Your own gem buttons, for example:
  document.querySelectorAll('[data-gem]').forEach((b) =>
    b.addEventListener('click', () =>
      send('apply-preset', { preset: { gem: b.dataset.gem } })));
</script>

8. Ring try-on

The shopper photographs the back of their hand and sees the ring — the one on screen, with its stone, metal, engraving and part colours — on their finger, sized and placed from the photo itself.

<iframe id="jc" src="https://jewelshop.ai/demo/?embed=1&tryon=1"
        allow="camera" allowfullscreen></iframe>

• &tryon=1 shows our Try on button over the viewer. Leave it off and open try-on from your own button with try-on-open instead.
• allow="camera" lets the viewer ask for the camera. Without it the button still works; shoppers upload a photo instead. The camera also needs your page on HTTPS.
• If your page sends its own Permissions-Policy header, it must allow the camera for us too, e.g. Permissions-Policy: camera=(self "https://jewelshop.ai"): camera=() or camera=(self) blocks it in the frame whatever the allow attribute says.
• Try-on opens inside the iframe, so give it room: on a phone it fills the frame.
• One at a time: a try-on-open while try-on is open or still loading is ignored.
• Hiding the viewer with pause closes try-on, so the camera never runs unseen; a pause or try-on-close while it is still loading cancels it.

document.getElementById('try-on').onclick = () => send('try-on-open', { hand: 'left' });
addEventListener('message', (e) => {
  if (e.data?.source !== 'jewelshop') return;
  if (e.data.kind === 'try-on-result') analytics.track('ring tried on', { model: e.data.model });
});

On the shopper's phone (QR code)

On a computer, try-on can show a QR code: the shopper scans it and the same product page opens on their phone, with the ring as configured and try-on already open — for a computer with no webcam, or a phone camera that is simply better. The code leads back to your page, with the configuration in parameters that start with jc_ (…/products/ring?variant=42&jc_gem=ruby&jc_size=60&jc_open=try-on). Two things need a few lines on your page, so the viewer shows the code only once you add them:

1. tell the viewer which page it is on (set-page-url) — an iframe can't read its parent's address;
2. on the phone, hand the jc_ parameters to the viewer (apply-link) and drop them from the address bar.

The Shopify theme block does both when Show ring try-on is on. Anywhere else, add this after the iframe:

<script>
  (function () {
    var frame = document.getElementById('jc');
    var page = new URL(location.href), link = new URLSearchParams();
    Array.from(page.searchParams.keys()).forEach(function (key) {
      if (key.indexOf('jc_') !== 0) return;
      link.set(key.slice(3), page.searchParams.get(key));
      page.searchParams.delete(key);
    });
    var told = false;
    window.addEventListener('message', function (e) {
      var d = e.data;
      if (told || e.source !== frame.contentWindow || !d || d.source !== 'jewelshop' || d.kind !== 'ready') return;
      told = true;
      var send = function (msg) { msg.source = 'jewelshop'; frame.contentWindow.postMessage(msg, e.origin); };
      send({ kind: 'set-page-url', url: page.href });
      if (link.toString()) {
        send({ kind: 'apply-link', query: link.toString() });
        history.replaceState(history.state, '', page.href);
      }
    });
  })();
</script>

The viewer takes only a page of the origin the message comes from, over HTTPS, so no page can put another site's address in the code. The link carries the stone, metal, ring and its look (size, setting, variants) — the same values as the URL parameters in section 2 — never the shopper's photo, which stays on the computer. Your own parameters (variant=42) are kept, so the phone opens the same variant.

Privacy. The photo is taken and processed in the shopper's browser — the hand tracking runs there too — and is never uploaded. Events tell your page only that try-on opened, closed, produced a result or failed, never the photo or a measurement.