Kivicube文档

简体中文

English

主题

iframe 事件 ​

本页描述宿主页面在 iframe DOM 上可监听的事件。

监听方式 ​

js
iframe.addEventListener('事件名', (event) => {
  console.log(event.detail);
});

除浏览器原生 load/error 外，插件事件都以 CustomEvent 形式派发，业务数据从 event.detail 读取。

事件总表 ​

事件名场景合辑说明
load支持支持iframe 页面资源加载完成
error支持支持加载错误或权限失败等
incompatibility支持支持兼容性前置检测失败
ready支持支持场景或合辑基础信息就绪
downloadAssetStart支持支持开始下载素材
downloadAssetProgress支持支持素材下载进度变化
downloadAssetEnd支持支持素材下载完成
loadSceneStart支持支持开始装载场景内容
loadSceneEnd支持支持场景内容装载完成
sceneStart支持支持场景开始，用户可体验
tracked支持支持成功追踪目标
lostTrack支持支持丢失追踪目标
openUrl支持支持触发网页跳转
cloudarStart不支持支持合辑开始云识别流程
cloudarEnd不支持支持合辑云识别结束并得到结果
sceneReady不支持支持合辑内部某个场景就绪
sceneDestroy不支持支持合辑切场景前销毁上一场景

load ​

ts
type LoadEvent = Event

表示 iframe 页面资源加载完成，不代表素材下载完毕。

error ​

ts
interface PluginErrorDetail {
  message: string;
  code?: number;
  isCameraNotFound?: boolean;
  isUserDeniedCamera?: boolean;
  isUserDeniedGyroscope?: boolean;
}

也可能直接是字符串。

如果是浏览器原生error事件触发，则是浏览器的Error事件对象。

incompatibility ​

ts
type IncompatibilityDetail = Record<string, any>

当前载荷结构暂不完全固定，常见于：

  • 当前浏览器不适合打开摄像头
  • 当前模式在该客户端不可用

ready ​

场景 ​

ts
interface SceneInfo {
  sceneId: string;
  name: string;
  description: string;
  thumbnailUrl: string;
  type: string;
  collectionId: string;
  collectionName: string;
  firstPage: {
    backgroundImageUrl?: string;
    logoUrl?: string;
    buttonUrl?: string;
    hideLogoAndName?: boolean;
    hideLogoAndSceneName?: boolean;
  };
  metadata: {
    htmlTitle?: string;
    share?: {
      title?: string;
      description?: string;
      picture?: string;
      pictureUrl?: string;
    };
  };
  setting: {
    skipScanMarker?: boolean;
    scanImage?: string;
    scanText?: string;
    hideScanImage?: boolean;
    userMarker?: string;
  };
  objects: Array<{
    id: number;
    name: string;
    type: string;
  }>;
}

interface SceneReadyDetail {
  sceneInfo: SceneInfo;
  api: SceneApi;
}

合辑 ​

ts
interface CollectionInfo {
  collectionId: string;
  name: string;
  description: string;
  thumbnailUrl: string;
  functionType: string;
  firstPage: {
    backgroundImageUrl?: string;
    buttonUrl?: string;
    hideLogoAndName?: boolean;
  };
  sceneList: string[];
  setting: {
    continue_scan?: number;
  };
}

interface CollectionReadyDetail {
  collectionInfo: CollectionInfo;
  api: object;
}

downloadAssetStart ​

ts
type DownloadAssetStartDetail = undefined

downloadAssetProgress ​

ts
type DownloadAssetProgressDetail = number

取值范围 0.0 - 1.0。

downloadAssetEnd ​

ts
type DownloadAssetEndDetail = undefined

loadSceneStart ​

ts
type LoadSceneStartDetail = undefined

loadSceneEnd ​

ts
type LoadSceneEndDetail = undefined

sceneStart ​

ts
type SceneStartDetail = undefined

tracked ​

ts
type TrackedDetail = undefined

lostTrack ​

ts
type LostTrackDetail = undefined

openUrl ​

ts
type OpenUrlDetail = string

detail 为即将打开的 URL。

cloudarStart ​

仅合辑支持。

ts
interface CloudarStartDetail {
  collectionId: string;
  sceneList: string[];
}

在合辑开始进行云识别时触发。

cloudarEnd ​

仅合辑支持。

ts
interface CloudarEndDetail {
  sceneId: string;
}

在合辑云识别结束并得到匹配结果时触发。

sceneReady ​

仅合辑支持。

ts
interface SceneReadyDetailInCollection {
  sceneInfo: SceneInfo;
  api: SceneApi;
}

sceneDestroy ​

仅合辑支持。

ts
interface SceneDestroyDetail {
  sceneId: string;
}

事件时序 ​

场景 ​

text
load
-> ready
-> downloadAssetStart
-> downloadAssetProgress
-> downloadAssetEnd
-> loadSceneStart
-> loadSceneEnd
-> sceneStart

合辑 ​

对于云识别合辑，通常会多出一段识别阶段：

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

如果是图像AR合辑，通常为：

text
load
-> ready
-> cloudarStart
-> cloudarEnd
-> sceneReady
-> downloadAssetStart
-> downloadAssetProgress
-> downloadAssetEnd
-> loadSceneStart
-> loadSceneEnd
-> sceneStart
-> tracked
-> lostTrack
-> cloudarStart
-> cloudarEnd

相关 Guide ​