Web版AR插件快速接入

案例展示

• 在进行插件的接入前，需要先熟悉在Kivicube平台上进行AR场景或合辑的创建

• 如果需要去除水印与Splash，请联系商务购买Kivicube高级版/企业版

• 如果需要使用插件属性与事件，请联系商务购买插件域名授权，域名授权支持迁移

Contact Us

---

创建场景或合辑

:目前支持的场景类型：

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

• 3D场景：3D互动

:目前支持的合辑类型：

• 图像AR

• 云识别/陀螺仪

插件接入

环境要求

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

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

kivicube lib代码引入

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

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

---

接入Kivicube场景

自动打开场景

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

调用API打开场景

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

// 全局变量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关闭了场景，否则容易内存泄漏。

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

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

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

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

隐藏场景资源加载提示

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

{
  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打开场景。

// 全局变量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关闭了合辑，否则容易内存泄漏。

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

{
  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. 扫描到当前合辑下，其他**同类型场景**时，会先关闭当前场景，再去打开新的场景。

---

示例代码

• 示例体验地址：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

模板代码

https://github.com/kivisense/kivicube-web-plugin-cases/tree/master/web-image2d-tracking