基础插件接入

Q 问题排查
A 使用Kivicube小程序AR插件遇到问题，可以尝试升级插件的版本，到这里查询更新日志
Q 插件未授权
A image.png
出现类似提醒，请到小程序管理后台申请插件
Q AR体验时出现报错：request:fail url not in domain list 是什么原因？
A 请给当前小程序配置服务器域名：https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html
官方提供的各种demo与sample中，包含了大量的官方CDN地址，请配置：
https://kivicube-resource.kivisense.com
Q 在体验场景/合辑的时候，能否自定义小程序UI？
A 基础版/高级版/企业版用户都可以进行基础的UI自定义，请参考开箱即用的示例代码：https://www.yuque.com/kivicube/manual/the-sun#FLdfG
针对企业版用户，还可以使用高级API完成更多的UI自定义：https://www.yuque.com/kivicube/manual/advanced-api
目前原生组件（如插件所需的camera组件）支持同层渲染，基础库2.12.0及其以上我们不推荐使用cover-image与cover-view
Q 开发过程中测试小程序
A Kivicube小程序AR插件不支持“真机调试”也暂不支持在开发者工具上运行，因为微信开发者工具存在BUG，所以可以暂时忽略在开发者工具上看到的报错，使用“预览”功能生成二维码，扫描打开正常体验即可。
image.png
Q 多种开发框架支持
A 请参考：https://mp.weixin.qq.com/wxopen/plugindevdoc?appid=wx3bbab3920eabccb2#dev-framework-sample
Q 接入Kivicube小程序AR插件后，超过了2M的限制，怎么解决？
A 因为Kivicube插件体积比较大，有近1.3M，所以很多情况下已有的小程序接入插件会超过2M（达到微信小程序的限制），建议进行分包处理，详细分包示例，使用方法查看官方文档 在分包内引入插件代码包，同时需要使用插件的setPackageRootPath方法，详细见此说明。也可直接查看我们提供的分包示例

|

Q 分包中接入插件后，分包内页面样式发生异常？
A 如果分包中接入插件后，分包内页面样式发生异常，请参考：分包中引入插件，会导致分包中页面样式不生效？
Q 接入Kivicube小程序AR插件后，发现插件提供的组件UI布局混乱、UI内容缺失或样式异常？
A 因为小程序插件的BUG，导致组件默认的display为inline，宽高变为0而不可见。因此，需要使用方按需将其设为block或inline-block等，之后可设置任意的宽高值。
若发现插件提供的组件UI布局混乱、UI内容缺失或样式异常，请检查app.wxss中，有没有使用标签选择器进行全局初始化，比如：canvas{position:relative}。如果有这样的行为，请尽量避免，插件组件自身无法解决被全局样式影响的问题。而使用方可以给插件组件所在页面配置页面样式隔离选项，确保页面不受全局样式影响，这样也能解决问题。
注意：当需要在组件上方叠加其他UI时，需使用绝对定位position: absolute|fixed，并且z-index >= 2。否则可能会被组件覆盖，导致叠加失败。
Q 接入Kivicube小程序AR插件后为什么做的【图像检测与跟踪场景】没有扫描图像就直接出现AR场景了，并且没有跟踪效果？
A 请更新最新的插件版本，即可正常使用图像检测与跟踪功能，此时使用会带水印，如需移除水印，请联系官方购买。详情请访问：https://www.yuque.com/kivicube/manual/kivicube-features#odsOp
Q 接入Kivicube小程序AR插件后点击拍照没有反应
A 接入插件后，点击拍照的后续逻辑需要开发者自定义，如保存到相册，或者在一个新页面显示拍摄的图片，然后进行保存或转发。
可以参考我们开箱即用的示例代码了解如何自定义：https://github.com/kivisense/wechat-kivicube-plugin-cases/tree/main/solar-divine-bird-mp
Q 手势滑动AR场景时，AR页面会被划走，显示出白色底
A 请更新最新插件版本
Q 进入AR场景时，加载时间过长是什么原因？
A 影响加载时长的因素比较多，首先请排除网络问题，即在标准的Wi-Fi或4G网络下测试。然后请按照如下排查：
是否素材过大，主要是模型与视频素材，关于模型素材，请参考官方规范：https://www.yuque.com/kivicube/manual/3d-model-specs；关于视频素材，一方面请进行压缩，请参考AR视频、透明视频，另一方面，可以使用高级API对加载外部素材，并且进行边下边播。
Q 打不开AR场景，报错”buffer exceed size limit”等错误 ，但是用web却可以体验AR场景是为什么？
A 在web上可以体验AR场景，小程序内却报错，大概率是因为素材不规范，文件过大导致的，因为微信小程序本身对素材文件的要求会比较严苛，所以需要特别注意一下素材的规范问题。
这里说一下在小程序中的素材最需要注意的几个地方，也就是大家最容易出错的部分：
- 模型：
- 贴图尺寸不能超过2048，否则素材或者整个AR场景都会不显示
- 当模型的UV设置为重复模式（Repeat）时，在小程序中使用时，贴图尺寸必须为2的幂次方（包括2、4、8、16、32、64、128、256、512、1024、2048），否则会出现UV重复不生效的问题
- 透明视频：尺寸最长边建议不能超过1560，否则可能会出现透明视频不显示或者卡顿等问题
- AR视频：尺寸长边不超过1280

更多小程序内AR素材特殊规范请查看：https://www.yuque.com/kivicube/manual/mp-specs |

Q 为什么在小程序中体验图像检测与跟踪场景或合辑AR画面没有Web端那么流畅？
A 目前在Android端，小程序与Web端的体验，基本保持一致
iOS端，受限于iOS系统的限制，运行速度会降低
我们建议有如下优化措施：
1. 保证AR场景中素材尽可能的小，尤其是模型的大小与网格数量以及视频的分辨率，更多关于素材的规范请参考：模型、AR视频、透明视频
1. 再使用图像跟踪合辑时，云识别与图像跟踪会同时打开，导致性能消耗过大。解决方案（会使用高级API）：在图像跟踪阶段暂停云识别，以提高性能，在想要扫描其它识别图时，可以点击“扫描其它卡片”，此时会重新打开云识别。对应代码示例链接：https://github.com/kivisense/wechat-kivicube-plugin-api-sample/tree/mp-wexin/pages/multi-continue-recognition/multi-tracking；详细说明请参考：https://www.yuque.com/kivicube/manual/advanced-api#Fq5AO
Q 做好的AR场景以web-view的方式嵌入到小程序，有些设备会显示“请到Safari中打开”
A 以web-view的方式嵌入小程序，体验设备若是iOS，那需要iOS版本≥14.3才可以打开，开发者可以预先判定，然后在打开AR场景的链接前进行引导
Q iOS上，touch事件穿透了view,image等标签，作用到了kivicube-scene等组件上
A 因为小程序自身存在问题，参考怎么防止canvas上方的view被穿透？、iOS，map上层的浮层点击会穿透浮层触发map的事件。
总而言之，在iOS上，当同层渲染的组件(kivicube-scene、kivicube-collection、canvas、camera等)在下，非cover-view/cover-image标签覆盖在上时，会出现touch类事件同时作用在上下两层标签的问题。
给出2个解决方案，适用于不同的情况：
- 情况1：仅仅需要上层标签挡住touch事件不作用在下层，同时上层标签不需要点击、触摸等事件。例如：增加一张只有展示功能的示意图在上方。

解决方案：增加一个和上层标签同样大小位置的cover-view标签。
- 情况2：上层标签需要支持点击、触摸等事件，但不在乎下层组件的点击、手势等功能。例如：增加一个可交互的弹窗在上方。
解决方案：将组件的touchable属性设置为false，主动禁用下层组件的触摸相关功能。当上层标签隐藏或消失时，重置属性为true即可。 |

Q Kivicube小程序AR插件中各个组件有什么区别？
A kivicube 小程序AR插件有三个组件：Kivicube-scene组件、Kivicube-collection组件、Kivi-cloudar组件
- kivicube-scene组件：可直接打开Kivicube平台制作的AR场景，快速发布到自己的小程序上。如果有额外的功能需求，也可使用插件提供的高级API二次开发实现。
- kivicube-collection组件：用来打开Kivicube的合辑(或者叫项目，两者是同一个概念)，可连续体验合辑中的多个同类型场景，而无需打断用户。如果有额外的功能需求，也可使用插件提供的高级API二次开发实现。
- kivi-cloudar组件：只单纯提供云识别功能，扫描到识别图之后的功能，由使用者自行开发实现。比如用来扫“福”、扫“Logo”、扫“海报”等

注意：
kivicube-scene和kivicube-collection这两个组件传递出的高级API对象，是完全不一样的。两者拥有完全不相同的API和信息。
我们一般将kivicube-scene组件传递出的高级API对象命名为view，将kivicube-collection组件传递出的高级API对象命名为collection。
重要：kivicube-collection组件还会通过特有的sceneReady事件，传递出和kivicube-scene组件一样的view对象。
当合辑打开新场景，关闭旧场景时，仍会通过sceneReady事件传递出新场景的view对象。每个新打开的场景都拥有新的view对象，且和旧场景的view对象是不一样的实例(console.log(oldView === newView); // 输出false)。
如果合辑中，对同一个场景打开了两次，那获取到的view对象也是不一致的。 |

Q iOS上，touch事件穿透了view,image等标签，作用到了kivicube-scene等组件上
A 因为小程序自身存在问题，参考怎么防止canvas上方的view被穿透？、iOS，map上层的浮层点击会穿透浮层触发map的事件。
总而言之，在iOS上，当同层渲染的组件(kivicube-scene、kivicube-collection、canvas、camera等)在下，非cover-view/cover-image标签覆盖在上时，会出现touch类事件同时作用在上下两层标签的问题。
给出2个解决方案，适用于不同的情况：
- 情况1：仅仅需要上层标签挡住touch事件不作用在下层，同时上层标签不需要点击、触摸等事件。例如：增加一张只有展示功能的示意图在上方。

解决方案：增加一个和上层标签同样大小位置的cover-view标签。
- 情况2：上层标签需要支持点击、触摸等事件，但不在乎下层组件的点击、手势等功能。例如：增加一个可交互的弹窗在上方。
解决方案：将组件的touchable属性设置为false，主动禁用下层组件的触摸相关功能。当上层标签隐藏或消失时，重置属性为true即可。 |

Q 进一步认识kivi-cloudar组件
A 仅仅是打开摄像头，以及拥有识别功能（图像云识别、AI识别），不具有3D渲染、Kivicube编辑器交互功能（如模型点击播放等）功能，但是它依然可以处理很多实际的需求。
例如：
- 需求只需要扫描识别到后，在屏幕上播放一段视频，那么可以直接使用小程序的video组件播放（包括变下边播）即可；
- 需求只需要扫描识别到后，会有一些2D的动画，那么可以直接使用小程序的组件（如image、canvas等）实现想要的动画，甚至还可以接入一些动画库，如lottie

此外，使用kivi-cloudar也可以实现kivicube-collection的合辑功能，即多图识别。
在Kivicube平台上创建好项目（合辑），然后再合辑中创建多个场景，kivi-cloudar组件进行图像识别的时候，如果识别到，会返回识别到的图像对应的场景id |

Q 灵活使用kivicube-scene与kivicube-collection组件
A 1、需要了解kivicube-scene与kivicube-collection的一些限制：这两个组件都会引入3D渲染功能，此功能会消耗一定的性能，如果自己的AR需求没有如下功能，可以考虑使用kivi-cloudar：
- 图像检测与跟踪功能
- AR场景是在3D空间中，而并非只在屏幕中（如，你的需求仅仅是在屏幕上播放一个AR视频）
- 模型展示与透明视频展示

2、对AR视频的灵活使用，如果AR需求比较复杂，仅有3D空间中的需求，也会在屏幕上播放AR视频，那么我们建议屏幕上的AR视频，直接使用小程序的video组件播放即可
3、可以将我们插件看做是一个AR层，开发者可以很灵活的在AR层上叠加更多的内容，视频、动画等 |

高级API使用

Q 在使用云识别合辑的时候，一定要点一下返回按钮才可以继续识别吗?
A 是的，如果觉得影响体验，那可以从应用层优化一下交互模式，自然地推进交互去达到一定连续识别的效果。
例如，做一个连续集卡的互动，扫描到一张卡片后，弹出获取的卡片，并且加上按钮（继续收集），用户点击此按钮后，就可以继续云识别扫描收集更多的卡片。
此修改需要使用高级API，参考此链接，详细了解使用方案：https://www.yuque.com/kivicube/manual/advanced-api#2by2d
Q 能否使用自己云服务器、OSS或CDN等上的素材
A 可以使用，请使用高级API加载三方素材
Q 使用高级API出错
A
1. 请检查加载的Kivicube场景或合辑是企业版账号创建的
1. 更新到插件最新版或查阅当前高级API所依赖的插件版本并升级到此版本