立即体验按钮

默认情况下，素材下载完成后，Kivicube 会展示“立即体验”按钮，等待用户点击后再真正进入场景。

为什么默认保留这个按钮

它不仅是一个 UI 元素，也承担了浏览器媒体策略上的作用：

让浏览器知道是用户在请求打开摄像头，否则可能打开失败
为音频和视频提供用户手势来激活，方便后续正常播放
避免在资源刚下载完就立即进入体验造成闪屏或突兀切换
给宿主层留出展示说明、提示权限的时间

强制隐藏

可以通过属性 hideStart 强制隐藏：

await kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId,
  hideStart: true,
});

或在 HTML 中写：

html

<iframe id="kivicubeScene" scene-id="..." hide-start></iframe>

隐藏后的影响

页面背景可能变黑或白，因为摄像头打开失败
素材下载完成后会直接开始加载，进入AR体验，不出现此按钮
如果场景里有视频或音频，浏览器可能拦截播放请求
插件内部会打印提醒日志，提示你这个选项可能导致媒体不能自动播放

更稳妥的替代方案

比起直接 hideStart，更推荐：

保留平台的开始逻辑
或者宿主自己自定义一个“立即体验”按钮
在用户点击后再允许流程继续

如果你的业务一定要按钮存在才能功能正常，建议用宿主层按钮配合默认流程事件，而不是粗暴自动进入。

适合隐藏的场景

纯 Web3D 展示，无音视频播放要求
体验流程非常短，希望减少一步点击

不建议隐藏的场景

视频、音频较多，且有需求进行自动播放
需要用户先明确授权或阅读提示

自定义立即体验按钮

如果你想保留 Kivicube 原生“立即体验”按钮提供的默认能力，但又希望把按钮和宿主页 UI 对齐，可以使用场景或合辑高级 API 提供的两个方法：

getStartButtonRect(): Promise<DOMRect | undefined>
setStartButtonRect(rect: Partial<CSSStyleDeclaration>): Promise<void>

getStartButtonRect() 返回 iframe 内真实按钮的 getBoundingClientRect() 结果。
setStartButtonRect(rect) 会把传入对象合并到按钮的内联样式上，常用字段包括 position、left、top、right、bottom、width、height、transform。

获取方式

场景页中，在 ready 事件里拿到 SceneApi：

let api = null;

iframe.addEventListener('ready', (event) => {
  api = event.detail.api;
});

合辑页中，在 ready 事件里拿到 CollectionApi：

let api = null;

iframe.addEventListener('ready', (event) => {
  api = event.detail.api;
});

什么时候调用

只有开始按钮真实存在时，这两个方法才有意义。
如果配置了 hideStart: true，通常不会再有可读取、可调整的按钮。
更稳妥的调用时机通常是 downloadAssetEnd 之后，或你确认按钮已经显示时。
如果调用过早，getStartButtonRect() 可能返回 undefined，setStartButtonRect() 也可能不会生效。

示例：读取按钮区域，在宿主层覆盖自定义按钮

let api = null;

iframe.addEventListener('ready', (event) => {
  api = event.detail.api;
});

iframe.addEventListener('downloadAssetEnd', async () => {
  const rect = await api.getStartButtonRect();
  if (!rect) {
    return;
  }

  Object.assign(hostStartButton.style, {
    display: 'block',
    position: 'fixed',
    left: `${rect.left}px`,
    top: `${rect.top}px`,
    width: `${rect.width}px`,
    height: `${rect.height}px`,
    pointerEvents: 'none',
  });
});

这样可以在宿主页的相同位置覆盖一个自己的按钮外观，同时让点击穿透到 iframe 中真正的按钮，继续保留原始按钮的点击手势。

示例：直接调整 iframe 内按钮的位置和大小

await api.setStartButtonRect({
  position: 'absolute',
  left: '24px',
  bottom: '32px',
  width: 'calc(100% - 48px)',
  height: '52px',
});

推荐优先传入带单位的 CSS 字符串值，例如 24px、52px、calc(...)。其中 0 这类值也可以直接使用数字。

常见做法

宿主页在相同位置覆盖一个自定义按钮，并设置 CSS pointer-events: none，让点击继续落到 iframe 的真实按钮上。
宿主页在按钮区域镂空一个点击区域，让用户直接点击下方 iframe 中的按钮，同时继续使用 iframe 自带的按钮样式。
通过 setStartButtonRect() 直接把 iframe 内按钮移动到新的位置，再和宿主层标题、提示文案、品牌装饰进行对齐。

立即体验按钮 ​

为什么默认保留这个按钮 ​

强制隐藏 ​

隐藏后的影响 ​

更稳妥的替代方案 ​

适合隐藏的场景 ​

不建议隐藏的场景 ​

自定义立即体验按钮 ​

获取方式 ​

什么时候调用 ​

示例：读取按钮区域，在宿主层覆盖自定义按钮 ​

示例：直接调整 iframe 内按钮的位置和大小 ​

常见做法 ​