DANGER

如果将自研H5最后放到微信小程序中，则还需要加入业务域名：www.kivicube.com，企业用户拥有此权益

案例展示

体验案例

INFO

在进行插件的接入前，需要先熟悉在Kivicube平台上进行AR场景或合辑的创建
如果需要去除水印与Splash，请联系商务购买Kivicube高级版/企业版
如果需要使用插件属性与事件，请联系商务购买插件域名授权，域名授权支持迁移

商务微信

创建场景或合辑

../../getting-started/legacy-docs/quick-start

INFO

目前支持的场景类型：

AR场景：图像AR（图像检测与跟踪）、云识别/陀螺仪
3D场景：3D互动

陀螺仪场景中的陀螺仪效果会失效。

INFO

目前支持的合辑类型：

图像AR
云识别/陀螺仪

合辑中陀螺仪的效果会失效。

插件接入

环境要求

WARNING

使用iframe标签的网页(自研H5所在页面)，必须运行在https协议上，或者使用http://localhost访问。否则iframe之中的网页因无法打开摄像头，而会出现类似“仅支持iOS11及以上系统”的相关提示。

不建议在开发环境(使用了类似192.168.x.x/172.16.x.x/10.x.x.x的内网地址)中接入测试，除非你知道如何在开发环境中配置好https协议，并让手机正常访问，否则都建议部署到线上环境(也必须确保支持https访问)进行测试。

kivicube lib代码引入

html

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

配置iframe标签

html

<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>

接入Kivicube场景

自动打开场景

当在页面中增加了一个id为“kivicubeScene”的iframe标签，同时指定了scene-id属性时，引入的lib代码会自动去打开指定的场景。【如上面的代码所示】

调用API打开场景

当未指定iframe标签的id为“kivicubeScene”，或scene-id属性未指定时，意味着需要开发者自行调用API打开场景。

javascript

// 全局变量kivicubeIframePlugin来自于引入的kivicube lib代码。
kivicubeIframePlugin.openKivicubeScene(document.querySelector("iframe"), {
  sceneId: "rDM7kXvo1UJKHnQUR46s7neoCSutDul9",
  hideLogo: true, // 是否隐藏首页Logo。默认false
  hideTitle: false, // 是否隐藏首页title。默认false
  hideDownload: false, // 是否隐藏下载进度条。默认false
  cameraPosition: "back", // front: 前置摄像头，back: 后置摄像头。默认后置。
  hideLoading: true, // 是否隐藏加载进度条。默认false
  hideScan: false, // 是否隐藏默认的扫描UI和提示文字。默认false
  hideTakePhoto: false, // 是否隐藏拍照按钮。默认false
  hideBackground: true, // 是否隐藏场景背景。默认false。web3d场景有效。
});

关闭场景

直接移除iframe标签(从dom树删除，并移除所有dom对象引用)，或者将iframe的src改为其他url，或者置为“about:blank”，皆可关闭场景。可按需使用某种方案。但不管哪种方案，都需要调用API通知kivicube lib关闭了场景，否则容易内存泄漏。

javascript

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

// 方案1：iframe内容置为空。
// 注意：此方式在iOS微信上无效。请使用方案2.
iframe.src = "about:blank";
// 方案2：打开其他url。比如官方提供的空地址：https://www.kivicube.com/lib/empty.html
iframe.src = 'https://www.kivicube.com/lib/empty.html';
// 方案3：从dom树中移除
iframe.parentNode.removeChild(iframe);

// 重要并注意！！！：但最终都必须调用销毁API
kivicubeIframePlugin.destroyKivicubeScene(iframe);

支持的属性

场景ID

sceneId

场景ID的获取

在Kivicube平台上制作并保存场景之后，点击右上角”分享”按钮，然后点击”复制链接”，而链接中最后一个正斜杠，之后的一串字符，就是场景id

比如复制的链接为：https://www.kivicube.com/scenes/n5KxG0svcgNyZof1aWz2kGl6oHNh2JRl ，则n5KxG0svcgNyZof1aWz2kGl6oHNh2JRl 就是场景id

隐藏场景Logo

hideLogo

支持单独显示或隐藏首页的场景Logo，默认显示

桌面端本身没有场景Logo，使用此属性不会引起任何变化

隐藏场景标题

hideTitle

支持单独显示或隐藏首页的场景标题，默认显示

场景资源下载进度条与进度百分比

hideDownload

支持显示或隐藏下载进度条（移动端）与下载百分比（桌面端），默认显示

摄像头朝向

cameraPosition

支持设置摄像头为前置或后置，默认后置。前置 - front；后置 - back。
前置摄像头为镜像模式

强制隐藏开始体验按钮

hideStart

是否强制隐藏开始按钮。意味着资源下载完成后，可以直接打开场景，而不必等待用户点击。默认不隐藏

和场景编辑器的隐藏体验按钮功能一致。但此处会不管场景情况，强制隐藏。场景编辑器中只有符合某种条件才能隐藏。

INFO

因此要注意，如果场景中有自动播放的视频或音乐，则强制隐藏后，可能会不能自动播放！

隐藏场景资源加载提示

hideLoading

支持显示或隐藏AR/3D页面中的加载提示，默认显示

INFO

有时候由于加载时间很短，基本不会看到此提示
图像检测与跟踪与云识别场景需要等到场景资源加载完成后，才会显示扫描UI提示
3D互动场景在场景资源加载完成后，会直接呈现3D互动场景

隐藏扫描UI与提示文字

hideScan

支持显示或隐藏AR/3D页面中的扫描UI与提示文字，默认显示

隐藏拍照按钮

hideTakePhoto

支持显示或隐藏AR/3D页面中的拍照按钮，默认显示

隐藏场景背景

hideBackground

支持显示或隐藏AR/3D页面中的拍照按钮，默认显示

INFO

仅3D互动场景有效

禁用「打开网页」功能

disableOpenUrl

如果不满足于插件，默认的跳转页面来打开网页功能，则可以禁止此行为(location.href=url)

可以监听openUrl事件，获取跳转的url，然后自行进行下一步处置。

支持的事件

触发顺序

插件场景页面加载完毕

load

触发时机

当Kivicube Web版AR插件脚本代码加载完并开始打开场景，且插件从服务器下载完Kivicube页面时触发
接着开始获取场景数据
本质就是iframe标签的load事件

最佳实践

在一些网络环境下，尤其是弱网环境，插件的代码加载与Kivicube页面的下载会占用一些时间，开发者可以在这里环节自定义Loading效果

error

error

触发时机

Kivicube Web版AR插件内发生错误，会触发此事件

错误列表

错误阶段	错误信息	错误描述
开始初始化场景	获取场景信息失败！(200, 404)

获取场景数据完成

ready

触发时机

当Kivicube Web版AR插件获取到场景数据时触发
接着开始打开场景

场景数据

sceneInfo

javascript

{
  sceneId: '场景id',
  name: '场景名称',
  description: '场景描述',
  thumbnailUrl: '场景缩略图URL',
  mode: '场景类型',
  collectionId: '所属合辑id',
  collectionName: '所属合辑名称',
  firstPage: {},
  metadata: {},
  setting: { skipScanMarker: false },
  objects: [{
    id: '对象id',
    name: '对象名称',
    type: '对象类型',
  }]
}

开始下载场景素材

downloadAssetStart

触发时机

当Kivicube Web版AR插件开始下载场景素材时触发
接着开始下载场景素材

注意事项

iOS15+不会提前下载AR视频与透明视频素材，自动采用边下边播

下载场景素材进度

downloadAssetProgress

下载场景素材完成

downloadAssetEnd

触发时机

当Kivicube Web版AR插件下载完场景素材时触发

注意事项

iOS15+不会提前加载AR视频与透明视频素材，自动采用边下边播

开始加载场景素材

loadSceneStart

触发时机

未在后台编辑器中勾选【隐藏体验按钮】时，当用户点击【立即体验】按钮后触发
已经勾选【隐藏体验按钮】时，下载场景素材完成事件触发后会紧接着触发

场景素材加载完成

loadSceneEnd

触发时机

当Kivicube Web版AR插件加载完场景素材时触发

开始体验场景

sceneStart

触发时机

场景内容开始出现并可体验时触发

跟踪到识别图

tracked

触发时机

进行AR体验时，当相机画面中追踪到识别图时触发

注意

图像检测与跟踪场景才有此事件

丢失识别图

lostTrack

触发时机

进行AR体验时，当相机画面中丢失识别图时触发

注意

图像检测与跟踪场景才有此事件

打开网页

openUrl

触发时机

当场景创作者制定的交互，需要打开网页时，则会触发。「比如点击打开」

可以和属性『禁用「打开网页」功能』配合，实现自定义的效果。

比如用来纯粹的获取信息，或者用iframe来打开，或者新窗口打开等。

接入Kivicube合辑

自动打开合辑

当在页面中增加了一个id为“kivicubeCollection”的iframe标签，同时指定了collection-id属性时，引入的lib代码会自动去打开指定的合辑。【如「配置iframe标签」一节代码所示】

调用API打开合辑

当未指定iframe标签的id为“kivicubeCollection”，或collection-id属性未指定时，意味着需要开发者自行调用API打开场景。

javascript

// 全局变量kivicubeIframePlugin来自于引入的kivicube lib代码。
kivicubeIframePlugin.openKivicubeCollection(document.querySelector("iframe"), {
    collectionId: "cqcmzh",
    hideLogo: true, // 是否隐藏首页Logo。默认false
    hideTitle: false, // 是否隐藏首页title。默认false
    hideDownload: false, // 是否隐藏下载进度条。默认false
    cameraPosition: "back", // front: 前置摄像头，back: 后置摄像头。默认后置。
    hideStart: false, // 是否强制隐藏开始按钮。意味着资源下载完成后，直接打开合辑。默认false
    hideLoading: true, // 是否隐藏加载进度条。默认false
    hideScan: false, // 是否隐藏默认的扫描UI和提示文字。默认false
    hideTakePhoto: false, // 是否隐藏拍照按钮。默认false
    disableOpenUrl: false, // 是否禁用「打开网页」功能，使其无效。默认false
});

关闭合辑

直接移除iframe标签(从dom树删除，并移除所有dom对象引用)，或者将iframe的src改为其他url，或者置为“about:blank”，皆可关闭合辑。可按需使用某种方案。但不管哪种方案，都需要调用API通知kivicube lib关闭了合辑，否则容易内存泄漏。

javascript

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

// 方案1：iframe内容置为空。
// 注意：此方式在iOS微信上无效。请使用方案2.
iframe.src = "about:blank";
// 方案2：打开其他url。比如官方提供的空地址：https://www.kivicube.com/lib/empty.html
iframe.src = 'https://www.kivicube.com/lib/empty.html';
// 方案3：从dom树中移除
iframe.parentNode.removeChild(iframe);

// 重要并注意！！！：但最终都必须调用销毁API
kivicubeIframePlugin.destroyKivicubeCollection(iframe);

支持的属性

合辑ID

collectionId

合辑ID的获取

可在Kivicube平台的「我的合辑」之中，找到想要的合辑，右下角菜单复制出合辑ID。如下所示：

隐藏首页Logo

hideLogo

支持单独显示或隐藏首页的合辑Logo，默认显示

隐藏首页Title

hideTitle

支持单独显示或隐藏首页的合辑标题，默认显示

隐藏下载进度条

hideDownload

支持显示或隐藏下载进度条（移动端），默认显示

摄像头朝向

cameraPosition

支持设置摄像头为前置或后置，默认后置。前置 - front；后置 - back。
前置摄像头为镜像模式

隐藏开始体验按钮

hideStart

是否强制隐藏开始按钮。意味着资源下载完成后，可以直接打开合辑，而不必等待用户点击。默认不隐藏

INFO

要注意，如果合辑中有自动播放的视频或音乐，则强制隐藏后，可能会不能自动播放！

隐藏加载进度提示

hideLoading

支持显示或隐藏AR/3D页面中的加载提示，默认显示

INFO

有时候由于加载时间很短，基本不会看到此提示
图像检测与跟踪与云识别场景需要等到场景资源加载完成后，才会显示扫描UI提示
3D互动场景在场景资源加载完成后，会直接呈现3D互动场景

隐藏扫描UI与提示文字

hideScan

支持显示或隐藏AR/3D页面中的扫描UI与提示文字，默认显示

隐藏拍照按钮

hideTakePhoto

支持显示或隐藏AR/3D页面中的拍照按钮，默认显示

禁用「打开网页」功能

disableOpenUrl

如果不满足于插件，默认的跳转页面来打开网页功能，则可以禁止此行为(location.href=url)

可以监听openUrl事件，获取跳转的url，然后自行进行下一步处置。

支持的事件

触发顺序

插件合辑页面加载完毕

load

触发时机

当Kivicube Web版AR插件脚本代码加载完并开始打开合辑，且插件从服务器下载完Kivicube页面时触发
接着开始获取合辑数据
本质就是iframe标签的load事件

最佳实践

在一些网络环境下，尤其是弱网环境，插件的代码加载与Kivicube页面的下载会占用一些时间，开发者可以在这里环节自定义Loading效果

error

error

触发时机

Kivicube Web版AR插件内发生错误，会触发此事件

获取合辑信息完毕

ready

触发时机

当Kivicube Web版AR插件获取到场景数据时触发
接着开始打开场景

合辑数据

collectionInfo

javascript

{
  collectionId: '合辑ID',
  name: '合辑名称',
  description: '合辑描述',
  thumbnailUrl: '合辑缩略图URL',
  functionType: '合辑类型',
  firstPage: {
    backgroundImageUrl: '首页背景图URL',
    buttonUrl: '首页按钮图URL',
    HideLogoAndName: true, // 是否隐藏掉合辑logo和名称
  },
  sceneList: ['合辑里面可打开的场景id'],
}

合辑中打开的场景做好准备

sceneReady

参考场景的「获取场景数据完成」，事件功能是一致的，仅仅名称不一样。

开始下载场景素材

downloadAssetStart

参考场景的「开始下载场景素材，事件功能是一致的。

下载场景素材进度

downloadAssetProgress

参考场景的「下载场景素材进度」，事件功能是一致的。

下载场景素材完成

downloadAssetEnd

参考场景的「下载场景素材完成」，事件功能是一致的。

开始加载场景素材

loadSceneStart

参考场景的「开始加载场景素材」，事件功能是一致的。

场景素材加载完毕

loadSceneEnd

参考场景的「场景素材加载完毕」，事件功能是一致的。

场景可开始体验

sceneStart

参考场景的「场景可开始体验」，事件功能是一致的。

追踪到识别图

tracked

参考场景的「追踪到识别图」，事件功能是一致的。

丢失识别图

lostTrack

参考场景的「丢失识别图」，事件功能是一致的。

打开网页

openUrl

参考场景的「打开网页」，事件功能是一致的。

合辑中的场景被销毁

sceneDestroy

事件参数会传递出关闭的场景id

触发时机

点击「返回」按钮，回到扫描界面时。仅当合辑为「云识别」类型时触发
扫描到当前合辑下，其他同类型场景时，会先关闭当前场景，再去打开新的场景。

实用功能

自定义统计

TODO

自定义UI/UX交互

TODO

自定义H5接入自研APP

TODO

示例代码

INFO

示例体验地址：https://meta.kivisense.com/kivicube-lib-iframe-demo/index.html

复制右侧地址至浏览器打开，可查看示例代码：view-source:https://meta.kivisense.com/kivicube-lib-iframe-demo/index.html

模板代码

INFO

请参考AR裸眼插画案例中【自研H5接入AR】部分

更新日志

2025年3月7日

新增合辑接入支持

FAQ

Web版AR插件FAQ

快速使用Kivicube

其它方案1：直接导出glb

其它方案2：使用Unity导出glb

Kivicube管理控制台

案例展示 ​

创建场景或合辑 ​

插件接入 ​

环境要求 ​

kivicube lib代码引入 ​

配置iframe标签 ​

接入Kivicube场景 ​

自动打开场景 ​

调用API打开场景 ​

关闭场景 ​

支持的属性 ​

场景ID ​

隐藏场景Logo ​

隐藏场景标题 ​

场景资源下载进度条与进度百分比 ​

摄像头朝向 ​

强制隐藏开始体验按钮 ​

隐藏场景资源加载提示 ​

隐藏扫描UI与提示文字 ​

隐藏拍照按钮 ​

隐藏场景背景 ​

禁用「打开网页」功能 ​

支持的事件 ​

触发顺序 ​

插件场景页面加载完毕 ​

触发时机 ​

最佳实践 ​

error ​

触发时机 ​

错误列表 ​

获取场景数据完成 ​

触发时机 ​

场景数据 ​

开始下载场景素材 ​

触发时机 ​

注意事项 ​

下载场景素材进度 ​

​

下载场景素材完成 ​

触发时机 ​

注意事项 ​

开始加载场景素材 ​

触发时机 ​

​

场景素材加载完成 ​

触发时机 ​

开始体验场景 ​

触发时机 ​

跟踪到识别图 ​

触发时机 ​

注意 ​

丢失识别图 ​

触发时机 ​

注意 ​

打开网页 ​

触发时机 ​

接入Kivicube合辑 ​

自动打开合辑 ​

调用API打开合辑 ​

关闭合辑 ​

支持的属性 ​

合辑ID ​

隐藏首页Logo ​

隐藏首页Title ​

隐藏下载进度条 ​

摄像头朝向 ​

隐藏开始体验按钮 ​

隐藏加载进度提示 ​

隐藏扫描UI与提示文字 ​

隐藏拍照按钮 ​

禁用「打开网页」功能 ​

支持的事件 ​

触发顺序 ​

插件合辑页面加载完毕 ​

触发时机 ​

最佳实践 ​

案例展示

创建场景或合辑

插件接入

环境要求

kivicube lib代码引入

配置iframe标签

接入Kivicube场景

自动打开场景

调用API打开场景

关闭场景

支持的属性

场景ID

隐藏场景Logo

隐藏场景标题

场景资源下载进度条与进度百分比

摄像头朝向

强制隐藏开始体验按钮

隐藏场景资源加载提示

隐藏扫描UI与提示文字

隐藏拍照按钮

隐藏场景背景

禁用「打开网页」功能

支持的事件

触发顺序

插件场景页面加载完毕

触发时机

最佳实践

error

触发时机

错误列表

获取场景数据完成

触发时机

场景数据

开始下载场景素材

触发时机

注意事项

下载场景素材进度

下载场景素材完成

触发时机

注意事项

开始加载场景素材

触发时机

场景素材加载完成

触发时机

开始体验场景

触发时机

跟踪到识别图

触发时机

注意

丢失识别图

触发时机

注意

打开网页

触发时机

接入Kivicube合辑

自动打开合辑

调用API打开合辑

关闭合辑

支持的属性

合辑ID

隐藏首页Logo

隐藏首页Title

隐藏下载进度条

摄像头朝向

隐藏开始体验按钮

隐藏加载进度提示

隐藏扫描UI与提示文字

隐藏拍照按钮

禁用「打开网页」功能

支持的事件

触发顺序

插件合辑页面加载完毕

触发时机

最佳实践

error

触发时机

获取合辑信息完毕

触发时机

合辑数据

合辑中打开的场景做好准备