Kivicube文档

简体中文

English

主题

Web版AR插件快速接入 ​

注意

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

案例展示 ​

体验案例

注意

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

商务微信

创建场景或合辑 ​

快速开始

1.目前支持的场景类型：

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

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

2.目前支持的合辑类型：

  • 图像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

hideLogo

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

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

隐藏场景标题 ​

hideTitle

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

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

hideDownload

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

摄像头朝向 ​

cameraPosition

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

强制隐藏开始体验按钮 ​

hideStart

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

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

注意

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

隐藏场景资源加载提示 ​

hideLoading

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

注意

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

隐藏扫描UI与提示文字 ​

hideScan

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

隐藏拍照按钮 ​

hideTakePhoto

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

隐藏场景背景 ​

hideBackground

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

注意

  • 仅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。如下所示：

hideLogo

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

隐藏首页Title ​

hideTitle

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

隐藏下载进度条 ​

hideDownload

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

摄像头朝向 ​

cameraPosition

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

隐藏开始体验按钮 ​

hideStart

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

注意

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

隐藏加载进度提示 ​

hideLoading

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

注意

  • 有时候由于加载时间很短，基本不会看到此提示
  • 图像检测与跟踪与云识别场景需要等到场景资源加载完成后，才会显示扫描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

触发时机 ​

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

实用功能 ​

自定义统计 ​

TODO

自定义UI/UX交互 ​

TODO

自定义H5接入自研APP ​

TODO

示例代码 ​

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

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

更多的示例代码 ​

https://github.com/kivisense/kivicube-web-plugin-quickstart

更新日志 ​

2025年3月7日 ​

  1. 新增合辑接入支持

FAQ ​