基础API示例代码

GitHub - kivisense/wechat-kivicube-plugin-quickstart

kivicube-scene 组件

支持的属性

属性名称	约束	值	说明
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 支持。

支持的事件

事件名称	说明
error	插件内发生错误，或 camera 发生问题，都会触发此事件
ready	已获取到场景数据，并准备开始去打开场景。event.detail 的值为一个对象，对象中属性 sceneInfo 可用来获取场景的一些基础数据(比如场景 id、类型、名称、合辑 id、缩略图、首页配置、分享信息等)。 除sceneInfo可拿到场景数据外，ready内使用其他API会触发开发者水印
downloadAssetStart	开始下载场景所需的素材。
downloadAssetProgress	下载素材时的进度通知。event.detail 的值范围为 0.0 - 1.0，代表下载的进度。
downloadAssetEnd	素材下载完毕。
loadSceneStart	开始将素材加载进场景。
loadSceneEnd	场景加载完毕。
cloudarStart	云识别开始。使用条件：此插件版本 >= 2.7.0 且场景为平面AR / 漫游AR
cloudarEnd	云识别结束。使用条件：此插件版本 >= 2.7.0 且场景为平面AR / 漫游AR
planeDetectStart	平面检测开始。使用条件：此插件版本 >= 2.7.0 且场景为平面AR
planeDetectEnd	平面检测结束。使用条件：此插件版本 >= 2.7.0 且场景为平面AR
tryLocateScene	尝试放置场景。使用条件：此插件版本 >= 2.7.0 且场景为平面AR 并使用自动放置。
indicatorVisible	指示器显示。使用条件：此插件版本 >= 2.7.0 且场景为平面AR 并使用指示器放置。
indicatorInvisible	指示器隐藏。使用条件：此插件版本 >= 2.7.0 且场景为平面AR 并使用指示器放置。
touchLocate	触摸放置。使用条件：此插件版本 >= 2.7.0 且场景为平面AR 并使用指示器放置。
locateDeviceStart	开始定位设备。使用条件：此插件版本 >= 2.8.5 且场景为漫游AR
locateDeviceEnd	设备定位结束。使用条件 >=2.8.5 且场景为漫游AR
sceneStart	场景内容开始出现并可体验。
unsupport	平面AR/漫游AR/世界AR场景中不支持设备或者条件的提示。使用条件：平面AR / 漫游AR场景中 此插件版本 >= 2.7.0，世界AR场景中，此插件版本 >= 2.8.0。
tracked	相机画面中追踪到识别图。使用条件：此插件版本>=1.4.0、基础库>=2.14.0，且需开通“图像AR”功能。插件版本>=1.6.0, 可以带水印使用
lostTrack	相机画面中丢失识别图。使用条件：此插件版本>=1.4.0、基础库>=2.14.0，且需开通“图像AR”功能。插件版本>=1.6.0, 可以带水印使用
anchored	扫描锚定到。使用条件：此插件版本 >= 2.8.5 且场景为世界AR
lostAnchor	画面中丢失锚定信息。使用条件：此插件版本 >= 2.8.6 且场景为世界AR
anchoring	持续锚定中。 使用条件：此插件版本 >= 2.8.5 且场景为世界AR
located	扫描定位到。 使用条件：此插件版本 >= 2.9.0 且场景为地标AR
lostLocate	扫描定位丢失。 使用条件：此插件版本 >= 2.9.0 且场景为地标AR
openUrl	因插件无法实现打开网页功能，所以当场景需要打开网页时，会触发此事件，交给插件使用者自行实现。event.detail 值为需要打开的网页 url
photo	当点击拍照按钮，且拍照成功后，可获取到照片文件的地址。e.detail 值为照片地址。开发者拿到照片文件地址，自己可以做显示与保存相册

触发顺序

3d互动 / 云识别 & 陀螺仪 / 图像AR / 世界AR / 地标AR 事件的触发时机依次为：

ready -> downloadAssetStart -> downloadAssetProgress -> downloadAssetEnd -> loadSceneStart -> loadSceneEnd -> sceneStart。

当场景为云识别 / 世界AR 类型时，在 loadSceneEnd 事件之后，会等待用户扫描识别图。如果用户扫描到当前场景识别图，才会触发 sceneStart 事件。

平面AR（使用指示器放置）事件的触发时机依次为：
事件的触发时机依次为：

ready -> downloadAssetStart -> downloadAssetProgress -> downloadAssetEnd -> loadSceneStart -> loadSceneEnd -> cloudarStart -> cloudarEnd -> planeDetectStart -> planeDetectEnd -> indicatorVisible / indicatorVisible -> touchLocate -> sceneStart。

平面AR（自动放置）事件的触发时机依次为：
事件的触发时机依次为：

ready -> downloadAssetStart -> downloadAssetProgress -> downloadAssetEnd -> loadSceneStart -> loadSceneEnd -> cloudarStart -> cloudarEnd -> planeDetectStart -> planeDetectEnd -> tryLocateScene（可能会多次触发） -> sceneStart。

漫游AR 事件的触发时机依次为：
事件的触发时机依次为：

ready -> downloadAssetStart -> downloadAssetProgress -> downloadAssetEnd -> loadSceneStart -> loadSceneEnd -> cloudarStart -> cloudarEnd -> locateDeviceStart -> locateDeviceEnd -> sceneStart。

kivicube-collection 组件

支持的属性

属性名称	约束	值	说明
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、缩略图、首页配置等)。 除collectionInfo可以拿到的合辑信息外，ready内使用其他API会触发开发者水印
cloudarStart	云识别开始时触发
cloudarEnd	识别到某张图，或主动结束云识别时触发。e.detail 值为对象{ sceneId: "" } (主动停止云识别时，返回空)。
sceneReady	参考 kivicube-scene 组件的 ready 事件说明，两者是同一个事件。
sceneDestroy	因为打开了其他场景，或主动关闭场景时触发。e.detail 值为对象{ sceneId: "" } 。
其他事件参考 kivicube-scene 组件“支持的事件”说明	除 ready 事件更改为 sceneReady 外，支持所有 kivicube-scene 组件的事件，并在打开场景时触发。

触发顺序

事件的触发时机依次为：

ready -> cloudarStart -> cloudarEnd -> sceneReady -> downloadAssetStart -> downloadAssetProgress -> downloadAssetEnd -> loadSceneStart -> loadSceneEnd -> sceneStart。

在 cloudarStart 事件之后，会等待用户扫描识别图。如果用户扫描到某张合辑中的识别图，才会去打开识别图对应的场景，从而触发 sceneReady 事件。
合辑中打开“云识别/陀螺仪”场景时，不会在 loadSceneEnd 事件后去等待用户扫描，会紧接着就触发 sceneStart 事件。意味着自动跳过了云识别【因为前面已经识别到了】。