属性

完整类型定义见插件 API。

所有属性名称，当在iframe标签上书写时，应使用全小写，单词用短横线连接方式(kebab-case)。

而在 JS 中书写时，应使用驼峰式(camelCase)。

html

<iframe
  id="kivicubeScene"
  scene-id="7A43keFojH0v98xvFP2w52aF8Y67Zbb5"
  hide-logo
></iframe>

布尔属性可省略 ="true"。

目前同时兼容三种写法：

kebab-case：hide-logo
camelCase：hideLogo
data 属性：data-hide-logo

但文档仍推荐使用标准的 HTML 写法，也就是 kebab-case。

注意：属性只在打开时读取一次。 场景或合辑开始打开后，再修改 iframe 上的属性不会生效；如需重新应用，必须重新执行 openKivicubeScene() 或 openKivicubeCollection()。

javascript

kivicubeIframePlugin.openKivicubeScene(iframe, {
  sceneId: "7A43keFojH0v98xvFP2w52aF8Y67Zbb5",
  hideLogo: true,
})

注意水印

当属性被指定为非默认值时，如果使用插件的域名，未被授权，则会出现开发者水印。

场景属性

sceneId

类型	约束	默认值	示例值
string	32位字符，必填。	无	rDM7kXvo1UJKHnQUR46s7neoCSutDul9

用以指定打开的场景

获取方式：

1.登录平台 - https://cloud.kivicube.com/scenes

2.然后按图示步骤获取：

获取场景id图示

hideLogo

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏场景首页的Logo

hideTitle

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏首页标题。

hideDownload

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏素材下载进度。

cameraPosition

类型	约束	默认值	示例值
string	`front` / `back`	back	front

指定首次打开时优先使用的摄像头。

hideLoading

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏“加载场景”阶段的默认加载 UI。

hideStart

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否强制隐藏“立即体验”按钮。开启后，素材下载完成会直接进入场景。

注意

强制隐藏可能导致视频、音频自动播放能力受浏览器限制而失效，从而无法播放音频、视频。也可能导致部分设备无法打开摄像头。

如果你只是想调整“立即体验”按钮的位置、大小，或在宿主页覆盖一个自定义按钮，优先参考立即体验按钮中的 getStartButtonRect() / setStartButtonRect()，通常不需要先打开 hideStart。

hideScan

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏默认扫描 UI 和提示文案。

hideRecordVideo

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏默认录屏按钮。

hideTakePhoto

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏默认拍照按钮。

hidePhotoPreview

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏默认的照片预览页。

如果hideTakePhoto为true，则照片预览页始终不会显示。
如果hideTakePhoto为默认值false，则可以影响插件自带照片预览页的显示。

隐藏后，可以监听插件的photo事件，自行实现照片预览页。此事件可获取拍照(点击默认拍照按钮)后的图片数据。拿到图片后，自行决定如何预览展示。

hideBackground

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏场景背景。这个属性主要对 3D互动 场景有意义。

hidePcGuide

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否隐藏PC端引导文案。

guideUrl

类型	约束	默认值	示例值
string	选填	''	https://my.domain.com/scenes/id

当未隐藏PC端引导文案时，可使用此属性配置引导UI上显示的链接地址。

disableOpenUrl

类型	约束	默认值	示例值
boolean	选填	false	true、false

是否禁用场景内“打开网页”行为。开启后，场景中的跳转动作不会执行，但宿主层仍然可以监听 openUrl 事件来决定是否自行处理。

注意： 默认情况下，打开链接的行为会在iframe内部进行。

如果跳转的链接，禁用iframe，则会打开失败，界面可能白屏或者报错。

此时有2个方案可选：

1. X-Frame-Options或CSP

如果跳转的链接，我们有能力进行配置(如果不行，则使用方案2)，可看是否有响应头X-Frame-Options，如果有则移除，这样就可以在iframe内打开。

如果响应的是CSP标头，则需要在策略中添加frame-ancestors字段，或者直接移除(一般不建议)，允许iframe在你的域名上打开此链接。

配置示例：Content-Security-Policy: frame-ancestors 'self' https://your-domain.com;

2. disableOpenUrl

使用disableOpenUrl属性，禁用在iframe内打开网页的行为，由宿主层监听openUrl自行处理。

合辑属性

合辑支持的大部分属性和场景一致，只是 id 从 sceneId 换成 collectionId，并额外支持 hideGyroscopePermission 与 hideBackToScan。

collectionId

类型	约束	默认值	示例值
string	6位字符，必填。	无	b46rfc

用于指定打开的合辑。

hideGyroscopePermission

类型	约束	默认值	示例值
boolean	选填	false	true、false

仅合辑支持。用于隐藏陀螺仪授权引导弹窗。

这个属性主要用于合辑中无陀螺仪需求时，期望不进行权限申请的情况。

hideBackToScan

类型	约束	默认值	示例值
boolean	选填	false	true、false

仅合辑支持。用于隐藏合辑云识别流程中的“继续扫描”按钮。

当你准备在宿主层自行提供“继续扫描”入口时，这个属性会比较有用。

其余属性和场景一致

场景与合辑的属性差异

属性	场景	合辑
`sceneId`	支持	不支持
`collectionId`	不支持	支持
`hideGyroscopePermission`	不支持	支持
`hideBackToScan`	不支持	支持

其余属性两者完全一致。

属性 ​

场景属性 ​

sceneId ​

hideLogo ​

hideTitle ​

hideDownload ​

cameraPosition ​

hideLoading ​

hideStart ​

hideScan ​

hideRecordVideo ​

hideTakePhoto ​

hidePhotoPreview ​

hideBackground ​

hidePcGuide ​

guideUrl ​

disableOpenUrl ​

1. X-Frame-Options或CSP ​

2. disableOpenUrl ​

合辑属性 ​

collectionId ​

hideGyroscopePermission ​

hideBackToScan ​

其余属性和场景一致 ​

场景与合辑的属性差异 ​

推荐做法 ​

属性