快速上手

注意

当前文档只说明Web端插件如何使用，如果要学习小程序端的使用，请打开小程序插件的指南页面。

快速嵌入网页中

如果你只需要把场景展示出来，不需要事件和高级 API，直接使用普通 iframe 即可。

<iframe
  src="https://www.kivicube.com/scenes/lU0kh9MnQBxa15Op5tcl3SJV53FWcSk6"
  allow="xr-spatial-tracking;camera;microphone;autoplay;fullscreen;gyroscope;accelerometer"
  frameborder="0"
  width="100%"
  height="100%"
></iframe>

重要必读

承载 iframe 的宿主网页必须运行在 https 协议上，或者使用 http://localhost，端口任意。

否则 iframe 内部页面无法正常获取摄像头权限，表现通常是无法进入 AR 或出现兼容性提示(比如“仅支持iOS11及以上系统”)。

不建议在手机上直接使用局域网地址(类似192.168.x.x、10.x.x.x、172.[16-31].x.x的地址)进行调试，除非你已经为该地址配置了可访问的 HTTPS。更稳妥的方式是部署到支持HTTPS的环境再调试。

src 可以替换为你自己的场景或合辑链接。平台中可通过「开发与接入」复制对应地址。

合辑的普通嵌入方式与场景完全一致，只需把 URL 换成 /collections/<collectionId> 即可。

以Plugin形式嵌入网页

如果你需要：

• 隐藏默认首页元素
• 自定义宿主层按钮和状态提示
• 监听下载、加载、识别、跳转等事件
• 在运行时新增图片、模型、视频等内容
• 读取对象并修改位置、旋转、灯光、相机等参数

那么应使用官方的 iframe 插件。

能力	普通iframe	Plugin形式
自定义UI	不支持	支持
事件通知	不支持	支持
AR内容增删改	不支持	支持
自定义拍照	不支持	支持
3D渲染更多控制	不支持	支持

1. 引入插件脚本

<script type="text/javascript" src="https://www.kivicube.com/lib/iframe-plugin.js"></script>

2. 准备 iframe 标签

<style type="text/css">
  iframe#kivicubeScene,
  iframe#kivicubeCollection {
    /* 按需设置宽高 */
    width: 100vw;
    height: calc(100vw * (4 / 3));
    /* 去除浏览器自带边框 */
    border: none;
  }
</style>

<!-- 接入场景 -->
<iframe id="kivicubeScene" scene-id="n5KxG0svcgNyZof1aWz2kGl6oHNh2JRl"></iframe>

<!-- 接入合辑 -->
<iframe id="kivicubeCollection" collection-id="b46rfc"></iframe>

如果 iframe 的 id 分别是 kivicubeScene 或 kivicubeCollection，并且在 DOMContentLoaded 触发时已经存在于页面中，插件会自动读取 scene-id 或 collection-id 并打开它。

注意事项

iOS上iframe不支持陀螺仪

对 iOS 宿主页面而言，陀螺仪授权能力被阻断。为了提升可用性，建议所有采用 iframe 嵌入的内容，优先关闭对陀螺仪的依赖。

陀螺仪的场景包含如下2类情况：

1. “云识别/陀螺仪”场景，去掉高级设置中的“陀螺仪”勾选

2. “图像AR”场景，去掉高级设置中的“陀螺仪”勾选

对于合辑，需要保证合辑中的相关场景也都关闭该选项。

支持的场景类型

iframe 插件的主要能力集中在：

• image2d-tracking - 图像AR
• cloud-ar - 云识别
• web3d - 3D互动

其他类型在 Web 端暂不提供等价的 iframe 高级 API，但会尽快支持。具体见后面的场景类型章节。

支持的合辑类型

iframe 插件的主要能力集中在：

• image2d-tracking - 图像AR
• cloud-ar - 云识别

其他类型在 Web 端暂不提供等价的 iframe 高级 API。具体见后面的合辑类型章节。

权益支持

所有注册用户皆可使用iframe嵌入自己的网站。

但不同用户，会有支持程度上的差异：

基础版、个人版用户的场景/合辑，会出现水印。

高级版、企业版用户的场景/合辑，没有水印。

如果使用了Plugin形式，且使用了属性或高级API功能，则会将普通水印，切换为开发者水印。

而开发者水印，需要通过域名授权去除。详细说明见下一页的去除水印。