简体中文
主题
DEMO仓库
https://github.com/kivisense/wechat-kivicube-plugin-api-demo
INFO
所有关于高级API的文档，请在DEMO仓库查阅
该仓库代码，列举了所有高级API的基本使用方式【包括API传参，返回值等详细说明】，可作为API说明文档使用。
原生微信小程序图像跟踪（图像AR场景）：打开小程序后，扫描左边识别图
如需移除图像AR场景水印，请联系商务
购买方式：联系sales@kivisense.com或微信联系商务
示例仓库
uni-app分支：https://github.com/kivisense/wechat-kivicube-plugin-api-sample
原生分支：https://github.com/kivisense/wechat-kivicube-plugin-api-sample/tree/mp-wechat
可作为高级API的应用示例学习参考，了解高级API可用来实现哪些功能【注意：仅为示例，不代表只能实现这些，期待您有更好的创意】。
示例详细说明
入门教程
注意：因为Kivicube插件体积比较大，所以很多情况下已有的小程序接入插件会超过2M（达到微信小程序的限制），我们建议进行分包处理，详细分包示例，可以参考如下示例：
https://github.com/kivisense/wechat-kivicube-plugin-samples/tree/master/subpackages
快速接入kivicube-scene组件
最简单的方式接入kivicube-scene组件，用来完成单场景识别，当中不涉及高级API的使用
快速接入kivicube-collection组件
最简单的方式接入kivicube-collection组件，用来完成多场景识别（多图连续识别），当中不涉及高级API的使用
使用”AR示例“分别扫描下方两张识别图进行体验。
场景设置
自定义UI与设置
（1）资源下载与加载UI
打开AR/3D场景，小程序首先会下载与加载资源素材，开发者可以自定义此过程的UI/UX。
注意：
① 由于微信小程序性能限制，尤其是iOS端，资源下载与加载速度相较于Web端会慢一些，所以我们建议素材一定要小；
② 同样的由于微信小程序性能限制，在资源加载过程中，开发者自定义的UI/UX（官方示例的转圈Loading）可能会出现卡顿，建议使用进度条类似的加载或者使用系统的加载，系统的加载可以参考3.1.4自动播放示例
（2）云识别扫描UI
资源下载与加载完后，进入云识别扫描阶段，这时需要通过UI/UX去引导用户扫描识别图片，开发者可以自定义此过程的UI/UX。
注意：
①由于微信小程序性能限制，云识别扫描UI/UX，不建议带动画，如下方微信扫码，中间有移动的扫描条，容易出现卡顿，建议使用AR示例中类似的扫描UI。同样的已修复，可以使用动态的UX，具体参考3.6多图连续识别中的UX实现
② 由于插件底层将整个相机画面采集并进行云识别，那么程序是期望识别图占整个相机画面越大越好，因此扫描的UI/UX一定要引导用户靠近识别（AR示例中3秒后，会出现“移近一点，保持扫描”的提示）；不建议使用下方支付宝类似的UI方式，因为会误导用户需要将识别图放在中间的框中，导致识别图距离较远，不易识别。
（3）拍照按钮
开发者可以隐藏插件自带的拍照按钮，然后自定义适合自己风格的按钮。
（4）自定义照片预览页
拍照完成后，开发者可以自定义一个预览页面，帮助开发者去保存照片；另一方面开发者也可以后期叠加更多的内容，比如水印与相框。
（5）****动态切换前后摄像头
开发者可以设置摄像头切换按钮，甚至可以通过高级API将前后摄像头设置不同的场景交互。
（6）自定义AR相框
开发者可以在相机画面上自定义各种2D内容，图片、按钮、序列帧、GIF、2D视频等等。
自定义跟踪UI
隐藏自带的跟踪扫描提示，开发者可以自定义跟踪扫描UI/UX，与云识别类似，用户在体验跟踪场景时，相机画面中识别图的区域占的越大越好，那么UI/UX的设计便是尽可能的引导用户靠近识别图。
使用”AR示例“，扫描下方识别图进行体验。
跳过云识别
针对陀螺仪/云识别场景，如果期望不需要扫描识别图，便可以直接体验，开发者可以在后台或者通过高级API跳过扫描。
尽管后台可以设置跳过扫描，但是有些特定的需求下，会有所需求，比如：期望用户扫描识别图体验，但是如果用户一直扫描不出来，便不能查看场景，那么可以设置用户10秒没有扫描到识别图，程序自动跳过扫描进入体验。
自动播放
场景可以不依赖后台设置的交互事件，开发者可以自定义交互事件，比如自己设置计时器，某些素材延迟2秒再自动播放，助力开发者构建丰富的互动。
素材管理
（1）允许开发者通过高级API加载自己的资源素材，如存放在开发者的CDN上的资源；
（2）素材管理，清除素材本地缓存或从内存中移除素材；
（3）修改素材的属性，包括位置、大小、旋转；
（4）AR视频与透明视频可以在线播放。
素材对象
模型控制
模型控制是后台基础交互事件之一，开放后，开发者可以自定义交互逻辑来控制场景中的模型素材，从而制作更加丰富的交互。
AR视频控制
AR视频控制是后台基础交互事件之一，开放后，开发者可以自定义交互逻辑来控制场景中的AR视频素材，从而制作更加丰富的交互。
注意：
如果不使用3D视频，其实我们更建议开发者可以在2D层自定义视频播放，比如实现视频适配、视频在线播放等；
透明视频控制
透明视频控制是后台基础交互事件之一，开放后，开发者可以自定义交互逻辑来控制场景中的AR视频素材，从而制作更加丰富的交互。
注意：
如果不使用3D视频，特殊情况，开发者也可以通过播放精灵图序列或序列帧代替；
音频控制
音频控制是后台基础交互事件之一，开放后，开发者可以自定义交互逻辑来控制场景中的音频素材，从而制作更加丰富的交互。
自定义动画
场景中素材，如模型素材，往往需要一些自定义动画让场景更加生动，另一方面也避免了一部分模型动画的制作。
此示例使用Tween实现了一个简单的入场动画。
模型遮罩
源场景中添加了名称为“柠檬”与“Occluder”的模型对象；将Occluder设置为遮罩类型，Occluder便可以挡住“柠檬”部分运动轨迹，达到柠檬跑到物体背后被遮挡，AR体验更真实。
对比上图，左图是有遮罩效果，右图无遮罩效果
扫描下方识别图体验：
特殊素材
自定义环境贴图
Kivicube的3D渲染采用现代化的PBR渲染，在PBR渲染中，环境贴图能够极大的提高模型场景质感。
精灵图序列
使用精灵图序列，开发者可以制作丰富的2D动效，比如某个模型动画播放完毕（如宝箱模型打开），屏幕上开始播放丰富的光效。
多图连续识别（kivicube-collection组件）
多个陀螺仪/云识别场景
本示例中首先自定义了云识别扫描UI；隐藏了云识别合辑的返回按钮，改为“扫描其它卡片”便可以继续扫描其它的场景识别图；新增了场景切换，点击场景中的“切换到霸王龙场景”或“切换鲨鱼场景”便可以进行场景切换。
扫描下面识别图进行体验。
多个图像AR场景
原始的插件，整个体验过程中（除了刚进入时只会仅仅打开云识别），系统一直会打开云识别与图像跟踪计算，导致性能消耗过大，此示例主要展示如何在图像跟踪阶段暂停云识别，以提高性能，用户想要扫描其它识别图时，可以点击“扫描其它卡片”，此时会重新打开云识别。
新增了场景切换，点击场景中的“切换到霸王龙场景”或“切换鲨鱼场景”便可以进行场景切换，这样便可以直接切换到另外的场景进行跟踪体验。
扫描下面识别图进行体验。
API
高级版及以上版本支持使用的基础API
WARNING
- 高级版仅支持部分API，使用其他部分API会出现开发者全屏水印
- 除云识别、陀螺仪、3D互动、平面AR、漫游AR场景外，使用其他场景类型与合辑功能会出现场景水印（非开发者全屏水印）
场景
支持的属性
| 无水印说明 | 属性名称 | 约束 | 值 | 说明 |
|---|---|---|---|---|
| 高级版及以上 | sceneId | 必填 | 场景 id | 在 kivicube 平台建立的场景 id。 |
 | ||||
| 高级版及以上 | cameraPosition | 选填 | front、back | 摄像头朝向。默认值 back |
| 高级版及以上 | renderCamera | 选填 | true、false | 是否使用 cameraFrame 来呈现相机画面(图像AR/平面AR/漫游AR/世界AR 类型场景会强制为 true，只有“云识别/陀螺仪”场景类型有效。应用情形：想要拍照无声音)。默认值 false。 插件版本>=1.6.6 支持。 |
| 高级版及以上 | resolution | 选填 | low、 medium、 high | 分辨率。默认值 medium |
| 高级版及以上 | flash | 选填 | auto、on、off、torch | 闪光灯。默认值 off（插件版本<2.10.0 时，默认为 auto） |
| 高级版及以上 | touchable | 选填 | true、false | 是否启用触摸相关功能(例如点击、手势操作等)。默认值 true 。 插件版本>=1.5.2 支持。 |
| 高级版及以上 | version | 选填 | tracking1、tracking2 | 设置图像AR版本，只在图像AR场景有效。 插件版本>=2.0.0 支持。不建议开发者设置。tracking2性能和稳定性更好（基础库2.24.5支持）。当运行环境不支持tracking2时，插件会自动切换到tracking1，tracking1能支持更广的运行环境 |
| 高级版及以上 | gesture | 选填 | orbit、trackball | 手势操作，只在3D互动、云识别（非陀螺仪）场景有效。 插件版本>=2.2.0 支持。 |
| 高级版及以上 | hideScan | 选填 | true、false | 是否隐藏默认的扫描提示文字。默认值 false |
| 高级版及以上 | hideDownload | 选填 | true、false | 是否隐藏下载场景素材时的默认提示文字。默认值 false |
| 高级版及以上 | hideLoading | 选填 | true、false | 是否隐藏加载场景时的默认提示文字。默认值 false |
| 高级版及以上 | hideTakePhoto | 选填 | true、false | 是否隐藏拍照按钮。默认值 false |
| 高级版及以上 | hideBackground | 选填 | true、false | 是否隐藏组件背景(3d 场景有效)。默认值 false。 插件版本>=1.7.4 支持。 |
| 高级版及以上 | hideSwitchCamera | 选填 | true、false | 隐藏切换摄像头。仅支持云识别/陀螺仪场景。 插件版本>=2.5.2 支持。 |
| 高级版及以上 | hideUnsupport | 选填 | true、false | 是否隐藏 平面AR/漫游AR场景中不支持的类型 UI 提示 默认值 false。 插件版本>=2.7.0 支持。 |
| 高级版及以上 | hidePlaneDetect | 选填 | true、false | 是否隐藏 平面AR场景中默认的平面扫描提示 UI 默认值 false。 插件版本>=2.7.0 支持。 |
支持的事件
| 无水印说明 | 属性名称 | 约束 | 值 | 说明 |
|---|---|---|---|---|
| 高级版及以上 | sceneId | 必填 | 场景 id | 在 kivicube 平台建立的场景 id。获取方式见下方说明 |
| 高级版及以上 | cameraPosition | 选填 | front、back | 摄像头朝向。默认值 back |
| 高级版及以上 | renderCamera | 选填 | true、false | 是否使用 cameraFrame 来呈现相机画面(图像AR/平面AR/漫游AR/世界AR 类型场景会强制为 true，只有“云识别/陀螺仪”场景类型有效。应用情形：想要拍照无声音)。默认值 false。 插件版本>=1.6.6 支持。 |
| 高级版及以上 | resolution | 选填 | low、 medium、 high | 分辨率。默认值 medium |
| 高级版及以上 | flash | 选填 | auto、on、off、torch | 闪光灯。默认值 off（插件版本<2.10.0 时，默认为 auto） |
| 高级版及以上 | touchable | 选填 | true、false | 是否启用触摸相关功能(例如点击、手势操作等)。默认值 true 。 插件版本>=1.5.2 支持。 |
| 高级版及以上 | version | 选填 | tracking1、tracking2 | 设置图像AR版本，只在图像AR场景有效。 插件版本>=2.0.0 支持。不建议开发者设置。tracking2性能和稳定性更好（基础库2.24.5支持）。当运行环境不支持tracking2时，插件会自动切换到tracking1，tracking1能支持更广的运行环境 |
| 高级版及以上 | gesture | 选填 | orbit、trackball | 手势操作，只在3D互动、云识别（非陀螺仪）场景有效。 插件版本>=2.2.0 支持。 |
| 高级版及以上 | hideScan | 选填 | true、false | 是否隐藏默认的扫描提示文字。默认值 false |
| 高级版及以上 | hideDownload | 选填 | true、false | 是否隐藏下载场景素材时的默认提示文字。默认值 false |
| 高级版及以上 | hideLoading | 选填 | true、false | 是否隐藏加载场景时的默认提示文字。默认值 false |
| 高级版及以上 | hideTakePhoto | 选填 | true、false | 是否隐藏拍照按钮。默认值 false |
| 高级版及以上 | hideBackground | 选填 | true、false | 是否隐藏组件背景(3d 场景有效)。默认值 false。 插件版本>=1.7.4 支持。 |
| 高级版及以上 | hideSwitchCamera | 选填 | true、false | 隐藏切换摄像头。仅支持云识别/陀螺仪场景。 插件版本>=2.5.2 支持。 |
| 高级版及以上 | hideUnsupport | 选填 | true、false | 是否隐藏 平面AR/漫游AR场景中不支持的类型 UI 提示 默认值 false。 插件版本>=2.7.0 支持。 |
| 高级版及以上 | hidePlaneDetect | 选填 | true、false | 是否隐藏 平面AR场景中默认的平面扫描提示 UI 默认值 false。 插件版本>=2.7.0 支持。 |
合辑
支持的属性
| 无水印说明 | 属性名称 | 约束 | 值 | 说明 |
|---|---|---|---|---|
| 高级版及以上 | collectionId | 必填 | 合辑 id | 在 kivicube 平台建立的合辑(项目)id(暂不支持“平面AR/漫游AR”类型合辑)。获取方式参考 kivi-cloudar 组件一节“获取合辑 id 方式” |
| 高级版及以上 | hideBackToScan | 选填 | true、false | 是否隐藏返回按钮【只有云识别类型合辑才有效】。默认值 false |
| 高级版及以上 | renderCamera | 选填 | true、false | 是否使用 cameraFrame 来呈现相机画面(“图像AR”类型合辑会强制为 true，只有“云识别”合辑类型有效。应用情形：想要拍照无声音)。默认值 false。 插件版本>=1.6.6 支持。 |
| 高级版及以上 | 其他属性参考 kivicube-scene 组件“支持的属性”说明 | 支持所有 kivicube-scene 组件的属性(除了 resolution、sceneId、hideSwitchCamera、hideUnsupport、hidePlaneDetect、gesture)，并在体验场景时生效。 |
支持的事件
| 无水印说明 | 事件名称 | 说明 |
|---|---|---|
| 高级版及以上 | error | 插件内发生错误、camera 发生问题、场景中出现错误等，都会触发此事件 |
| 高级版及以上 | ready | 已获取到合辑数据，并可开始扫描合辑中的识别图。event.detail 的值为一个对象，对象中属性 collectionInfo 可用来获取合辑的一些基础数据(比如名称、合辑 id、缩略图、首页配置等)。 |
| 高级版及以上 | cloudarStart | 云识别开始时触发 |
| 高级版及以上 | cloudarEnd | 识别到某张图，或主动结束云识别时触发。e.detail 值为对象{ sceneId: "" }(主动停止云识别时，返回空)。 |
| 高级版及以上 | sceneReady | 参考 kivicube-scene 组件的 ready 事件说明，两者是同一个事件。 |
| 高级版及以上 | sceneDestroy | 因为打开了其他场景，或主动关闭场景时触发。e.detail 值为对象{ sceneId: "" }。 |
| 高级版及以上 | 其他事件参考 kivicube-scene 组件“支持的事件”说明 | 除 ready 事件更改为 sceneReady 外，支持所有 kivicube-scene 组件的事件，并在打开场景时触发。 |
企业版支持使用的高级API
- 高级版及以上部分的全部API
- 其他高级API，参考示例：GitHub - kivisense/wechat-kivicube-plugin-api-demo