自研微信小程序接入 - 小程序插件高级API - 《Kivicube 用户文档 - 帮助手册 - 教程》

1.DEMO仓库
2.示例仓库
3.示例详细说明

:::info 开箱即用的示例代码，里面包含了部分高级API的使用示意：
https://github.com/kivisense/wechat-kivicube-plugin-cases :::

1.DEMO仓库

https://github.com/kivisense/wechat-kivicube-plugin-api-demo
企业版用户可申请

:::info 所有关于高级API的文档，请在DEMO仓库查阅 :::

该仓库代码，列举了所有高级API的基本使用方式【包括API传参，返回值等详细说明】，可作为API说明文档使用。

小程序AR图像跟踪体验：打开小程序后，扫描左边识别图

如需小程序图像跟踪功能，请联系商务
购买方式：联系sales@kivisense.com或微信联系商务

2.示例仓库

uni-app分支：https://github.com/kivisense/wechat-kivicube-plugin-api-sample
原生分支：https://github.com/kivisense/wechat-kivicube-plugin-api-sample/tree/mp-wexin
企业版用户可申请，此仓库为小程序“AR示例”的源代码。

可作为高级API的应用示例学习参考，了解高级API可用来实现哪些功能【注意：仅为示例，不代表只能实现这些，期待您有更好的创意】。

3.示例详细说明

3.1入门教程

注意：因为Kivicube插件体积比较大，有近1.3M，所以很多情况下已有的小程序接入插件会超过2M（达到微信小程序的限制），我们建议进行分包处理，详细分包示例，可以参考如下示例： https://github.com/kivisense/wechat-kivicube-plugin-samples/tree/master/subpackages

3.1.1创意者

如果您不具备小程序的开发能力，可以参考此链接完成小程序AR制作
https://www.kivicube.com/blog/mp-ar

3.1.2开发者

如果您具备小程序的开发能力，您需要先参阅如下文章，了解小程序AR制作的基础
https://www.kivicube.com/blog/mp-ar

3.1.3快速接入kivicube-scene组件

最简单的方式接入kivicube-scene组件，用来完成单场景识别，当中不涉及高级API的使用

3.1.4快速接入kivicube-collection组件

最简单的方式接入kivicube-collection组件，用来完成多场景识别（多图连续识别），当中不涉及高级API的使用

使用”AR示例“分别扫描下方两张识别图进行体验。

3.2场景设置

3.2.1自定义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视频等等。

3.2.2自定义跟踪UI

隐藏自带的跟踪扫描提示，开发者可以自定义跟踪扫描UI/UX，与云识别类似，用户在体验跟踪场景时，相机画面中识别图的区域占的越大越好，那么UI/UX的设计便是尽可能的引导用户靠近识别图。

使用”AR示例“，扫描下方识别图进行体验。

3.2.3跳过云识别

针对陀螺仪/云识别场景，如果期望不需要扫描识别图，便可以直接体验，开发者可以在后台或者通过高级API跳过扫描。

尽管后台可以设置跳过扫描，但是有些特定的需求下，会有所需求，比如：期望用户扫描识别图体验，但是如果用户一直扫描不出来，便不能查看场景，那么可以设置用户10秒没有扫描到识别图，程序自动跳过扫描进入体验。

3.2.4自动播放

场景可以不依赖后台设置的交互事件，开发者可以自定义交互事件，比如自己设置计时器，某些素材延迟2秒再自动播放，助力开发者构建丰富的互动。

3.2.5素材管理

（1）允许开发者通过高级API加载自己的资源素材，如存放在开发者的CDN上的资源；
（2）素材管理，清除素材本地缓存或从内存中移除素材；
（3）修改素材的属性，包括位置、大小、旋转；
（4）AR视频与透明视频可以在线播放。

3.3素材对象

3.3.1模型控制

模型控制是后台基础交互事件之一，开放后，开发者可以自定义交互逻辑来控制场景中的模型素材，从而制作更加丰富的交互。

3.3.2AR视频控制

AR视频控制是后台基础交互事件之一，开放后，开发者可以自定义交互逻辑来控制场景中的AR视频素材，从而制作更加丰富的交互。

注意： ① 如果不使用3D视频，其实我们更建议开发者可以在2D层自定义视频播放，比如实现视频适配、视频在线播放等； ② 小程序端AR视频循环播放目前存在一定问题，包括：（1）停止视频播放后，视频画面不会回到第一帧（https://www.yuque.com/kivicube/topics/10）； ~~（2）视频不能正常循环播放（https://www.yuque.com/kivicube/topics/8~~）；（~~3）Android端有些设备，视频不能正常播放（https://www.yuque.com/kivicube/topics/9~~）

3.3.3透明视频控制

透明视频控制是后台基础交互事件之一，开放后，开发者可以自定义交互逻辑来控制场景中的AR视频素材，从而制作更加丰富的交互。

注意： ① 如果不使用3D视频，特殊情况，开发者也可以通过播放精灵图序列或序列帧代替； ② 小程序端透明视频循环播放目前存在一定问题，包括：（1）停止视频播放后，视频画面不会回到第一帧（https://www.yuque.com/kivicube/topics/10）； ~~（2）视频不能正常循环播放（https://www.yuque.com/kivicube/topics/8~~）； ~~（3）Android端有些设备，视频不能正常播放（https://www.yuque.com/kivicube/topics/9~~）