Tryon Platform Advanced API

The current iframe integration uses a scene page URL. Set the iframe's src to open a scene.

Scene page path

https://www.kivicube.com/tryon-scenes/<sceneId>

Part	Requirement	Purpose
<sceneId>	Required; 32 letters or digits	Selects the Tryon scene to open

Copy the scene link from the Tryon Platform.

URL query parameters

Parameter	Required	Description
lang	No	zh for Chinese or en for English. Other or missing values use the browser language.
visitor-id	No	A unique user identifier used to track users who are not logged in. It must be 32 characters; the Tryon component generates one if omitted.
sections	No	A JSON array that matches works by name and overrides their links with webLink.
customSectionLinkClick	No	Set to true to let the host page handle work-link clicks and receive section-link-click events.

Join multiple parameters with &:

https://www.kivicube.com/tryon-scenes/<sceneId>?lang=en&visitor-id=<32-character user ID>

sections

Each array item needs a name matching a work in the scene. The optional webLink must be a valid HTTP or HTTPS URL. Only matching items with a webLink override the original link.

const url = new URL("https://www.kivicube.com/tryon-scenes/<sceneId>");
url.searchParams.set(
  "sections",
  JSON.stringify([{ name: "Work name", webLink: "https://example.com/product" }]),
);
iframe.src = url.href;

Events

The scene page sends events to the host page with window.parent.postMessage. Each message contains type and detail:

type	When triggered	detail parameters
section-link-click	When the scene URL has customSectionLinkClick=true and the user clicks a work with a valid link.	name: the work's name; webLink: its current link.

The host page can handle events by type. This example assumes the scene iframe has the ID tryonFrame:

const iframe = document.querySelector("#tryonFrame");

window.addEventListener("message", (event) => {
  if (event.source !== iframe?.contentWindow) return;
  if (event.origin !== new URL(iframe.src).origin) return;

  const message = event.data;
  if (typeof message?.type !== "string") return;

  console.log(message.type, message.detail);
});

Check both origin and source before using detail.