Kivicube文档

简体中文

English

主题

基础插件接入 ​

Q### 问题排查
A使用Kivicube小程序AR插件遇到问题，可以尝试升级插件的版本，到这里查询更新日志
Q### 插件未授权
A

出现类似提醒，请到小程序管理后台申请插件
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### AR体验时出现报错：request:fail url not in domain list 是什么原因？
A2.0.0-2.8.0 是根据配置的环境贴图的名字来处理的 目前使用新的 hdr 文件，与之前配置的环境贴图名都不一样，如果直接更改新的 hdr 配置，老版本会导致加载出错。
当小程序版本为 2.0.0-2.8.0 时候需要在kivicube场景编辑器中使用“******（旧）”的hdr文件

建议更新为2.8.5版本及以上，就不会出现此问题
Q### 在体验场景/合辑的时候，能否自定义小程序UI？
A基础版/高级版/企业版用户都可以进行基础的UI自定义，请参考开箱即用的示例代码：../../template-tutorials/image-ar-scenes/legacy-tutorials/the-sun
还可以使用高级API完成更多的UI自定义：../../custom-development/wechat-miniprogram/advanced-api
目前原生组件（如插件所需的camera组件）支持同层渲染，基础库2.12.0及其以上我们不推荐使用cover-image与cover-view
Q### 开发过程中测试小程序
AKivicube小程序AR插件不支持“真机调试”也暂不支持在开发者工具上运行，因为微信开发者工具存在BUG，所以可以暂时忽略在开发者工具上看到的报错，使用“预览”功能生成二维码，扫描打开正常体验即可。
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
Q接入Kivicube小程序AR插件后为什么做的【图像检测与跟踪场景】没有扫描图像就直接出现AR场景了，并且没有跟踪效果？
A请更新最新的插件版本，即可正常使用图像检测与跟踪功能，此时使用会带水印，如需移除水印，请联系官方购买。详情请访问：../../learn/kivicube-features
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网络下测试。然后请按照如下排查：
是否素材过大，主要是模型与视频素材，关于模型素材，请参考官方规范：../../ar-asset-creation-guide/3d-model-animation-workflow/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素材特殊规范请查看：../../ar-asset-creation-guide/mp-specs
Q为什么在小程序中体验图像检测与跟踪场景或合辑AR画面没有Web端那么流畅？
A目前在Android端，小程序与Web端的体验，基本保持一致
iOS端，受限于iOS系统的限制，运行速度会降低
我们建议有如下优化措施：
1. 保证AR场景中素材尽可能的小，尤其是模型的大小与网格数量以及视频的分辨率，更多关于素材的规范请参考：模型、AR视频、透明视频
2. 再使用图像跟踪合辑时，云识别与图像跟踪会同时打开，导致性能消耗过大。解决方案（会使用高级API）：在图像跟踪阶段暂停云识别，以提高性能，在想要扫描其它识别图时，可以点击“扫描其它卡片”，此时会重新打开云识别。对应代码示例链接：https://github.com/kivisense/wechat-kivicube-plugin-api-sample/tree/mp-wexin/pages/multi-continue-recognition/multi-tracking；详细说明请参考：../../custom-development/wechat-miniprogram/advanced-api
Q做好的AR场景以web-view的方式嵌入到小程序，有些设备会显示“请到Safari中打开”
A以web-view的方式嵌入小程序，体验设备若是iOS，那需要iOS版本≥14.3才可以打开，开发者可以预先判定，然后在打开AR场景的链接前进行引导
QiOS上，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即可。
QKivicube小程序AR插件中各个组件有什么区别？
Akivicube 小程序AR插件有两个组件：Kivicube-scene组件、Kivicube-collection组件
+ kivicube-scene组件：可直接打开Kivicube平台制作的AR场景，快速发布到自己的小程序上。如果有额外的功能需求，也可使用插件提供的高级API二次开发实现。
+ kivicube-collection组件：用来打开Kivicube的合辑(或者叫项目，两者是同一个概念)，可连续体验合辑中的多个同类型场景，而无需打断用户。如果有额外的功能需求，也可使用插件提供的高级API二次开发实现。
****
注意：
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对象也是不一致的。
QiOS上，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-scene与kivicube-collection组件
A1、需要了解kivicube-scene与kivicube-collection的一些限制：这两个组件都会引入3D渲染功能，此功能会消耗一定的性能
2、对AR视频的灵活使用，如果AR需求比较复杂，仅有3D空间中的需求，也会在屏幕上播放AR视频，那么我们建议屏幕上的AR视频，直接使用小程序的video组件播放即可
3、可以将我们插件看做是一个AR层，开发者可以很灵活的在AR层上叠加更多的内容，视频、动画等

高级API使用 ​

Q### 在使用云识别合辑的时候，一定要点一下返回按钮才可以继续识别吗?
A是的，如果觉得影响体验，那可以从应用层优化一下交互模式，自然地推进交互去达到一定连续识别的效果。
例如，做一个连续集卡的互动，扫描到一张卡片后，弹出获取的卡片，并且加上按钮（继续收集），用户点击此按钮后，就可以继续云识别扫描收集更多的卡片。
此修改需要使用高级API，参考此链接，详细了解使用方案：../../custom-development/wechat-miniprogram/advanced-api
Q### 能否使用自己云服务器、OSS或CDN等上的素材
A可以使用，请使用高级API加载三方素材
Q使用高级API出错
A1. 请检查加载的Kivicube场景或合辑是企业版账号创建的
2. 更新到插件最新版或查阅当前高级API所依赖的插件版本并升级到此版本
3. 使用最新版的插件，所有版本均可以使用高级API，但是会存在【高级API水印】，使用企业版可以移除
Qkivicube-collection组件返回值
A1. 只有云识别场景扫描后会返回sceneid
2. 图像跟踪场景不会，只有扫描识别到与丢失事件
Q如何写拍照获取图片的API
A在demo中全局搜索takephoto可以找到路径

示例问题 ​

Qdemo中部分场景拍照按钮无法使用
A1. 该示例场景没做拍照功能，请参考拍摄相关示例
2. 云识别的demo没有处理拍照完成后的功能，请直接查看专门拍照的demo
Q#### 反复重启场景导致二次开发小程序崩溃
A1. 销毁组件，回收资源（内存）
javascript // 销毁组件的时候清除资源 const { clearSceneCache } = requirePlugin("kivicube"); clearSceneCache(); 2. 或者可以在代码中全局搜索destroyObject，有相应示例
3. 请知悉：因系统限制，回收资源需要一定时间，所以即使加入以上方式，在重复开关之间也需要尽可能长的时间以保证系统有足够的时间回收资源
Q#### 插件报错，提示“下载素材失败下载素材失败 <TypeError: undefined is not an object (evaluating(0,f.getEvnMapData)(r).url')>”
A原因：接入场景时候，只能使用名称为“xxxx（旧）”的环境贴图

可以参考文档中的视频规范：AR视频