iframe Events

This page describes the events the host page can listen for on the iframe DOM element.

How to Listen

iframe.addEventListener('eventName', (event) => {
  console.log(event.detail);
});

Except for the browser-native load / error events, plugin events are dispatched as CustomEvent, and business data is read from event.detail.

Event List

Event name	Scene	Collection	Description
load	Supported	Supported	iframe page resources finished loading
error	Supported	Supported	loading error, permission failure, and so on
incompatibility	Supported	Supported	preflight compatibility check failed
ready	Supported	Supported	basic scene or collection information is ready
downloadAssetStart	Supported	Supported	asset download starts
downloadAssetProgress	Supported	Supported	asset download progress changes
downloadAssetEnd	Supported	Supported	asset download completes
loadSceneStart	Supported	Supported	scene content starts loading
loadSceneEnd	Supported	Supported	scene content finishes loading
sceneStart	Supported	Supported	scene starts and the user can enter the experience
tracked	Supported	Supported	target tracked successfully
lostTrack	Supported	Supported	target tracking lost
openUrl	Supported	Supported	webpage jump triggered
cloudarStart	Not supported	Supported	collection cloud recognition starts
cloudarEnd	Not supported	Supported	collection cloud recognition ends with a result
sceneReady	Not supported	Supported	a concrete scene inside the collection is ready
sceneDestroy	Not supported	Supported	previous scene is destroyed before switching

load

type LoadEvent = Event

Indicates that iframe page resources are loaded. It does not mean assets are finished downloading.

error

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

It may also be a plain string.

If the browser's native error event fires instead, the payload is the browser's Error event object.

incompatibility

type IncompatibilityDetail = Record<string, any>

The payload shape is not fully fixed for now. Common cases include:

• the current browser is not suitable for opening the camera
• the current mode is unavailable on this client

ready

Scene

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;
}

Collection

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

type DownloadAssetStartDetail = undefined

downloadAssetProgress

type DownloadAssetProgressDetail = number

Value range: 0.0 - 1.0.

downloadAssetEnd

type DownloadAssetEndDetail = undefined

loadSceneStart

type LoadSceneStartDetail = undefined

loadSceneEnd

type LoadSceneEndDetail = undefined

sceneStart

type SceneStartDetail = undefined

tracked

type TrackedDetail = undefined

lostTrack

type LostTrackDetail = undefined

openUrl

type OpenUrlDetail = string

detail is the URL about to be opened.

cloudarStart

Collections only.

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

Triggered when the collection starts cloud recognition.

cloudarEnd

Collections only.

interface CloudarEndDetail {
  sceneId: string;
}

Triggered when collection cloud recognition finishes and returns a matched scene.

sceneReady

Collections only.

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

sceneDestroy

Collections only.

interface SceneDestroyDetail {
  sceneId: string;
}

Event Order

Scene

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

Collection

For cloud-recognition collections, there is usually an extra recognition stage:

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

For image-ar collections, it is usually:

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

Related Guide Pages

• Events
• Download / Load / Scan
• Permission Handling