Tryon 平台高级API

当前 iframe 接入使用场景页 URL。宿主页面通过设置 iframe 的 src 打开场景。

场景页路径

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

部分	要求	作用
<sceneId>	必填，32 位英文字母或数字	指定要打开的 Tryon 场景

场景链接可从 Tryon 平台 复制。

URL 查询参数

参数	是否必填	说明
lang	否	zh 显示中文，en 显示英文；缺省或其他值按浏览器语言选择。
visitor-id	否	用户的唯一标识，用于记录未登录用户。须为 32 字符；未传时由试衣组件自动生成。
sections	否	JSON 数组，按作品 name 匹配，用 webLink 覆盖对应作品的跳转链接。
customSectionLinkClick	否	设为 true 时，点击作品链接由宿主页面处理，并发送 section-link-click 事件。

需要同时指定多个参数时，用 & 连接：

https://www.kivicube.com/tryon-scenes/<sceneId>?lang=zh&visitor-id=<32 字符用户标识>

sections

数组中的每项需要提供与场景作品名称一致的 name；可选的 webLink 必须是有效的 HTTP 或 HTTPS 链接。只有提供 webLink 的匹配项才会覆盖原链接。

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

事件

场景页通过 window.parent.postMessage 向宿主页面发送事件。消息包含 type 和 detail：

type	触发时机	detail 参数
section-link-click	场景 URL 设置 customSectionLinkClick=true，且用户点击带有有效链接的作品时触发。	name：作品名称；webLink：当前跳转链接。

宿主页面可根据 type 处理事件。以下示例假设场景 iframe 的 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);
});

接收消息时应同时核对 origin 和 source，再使用 detail。