Basic AR/Gyroscope

Basic AR/Gyroscope collections correspond to the cloud-ar type.

Compared with a single Basic AR/Gyroscope scene, the core characteristics of a Basic AR/Gyroscope collection are:

• one collection usually contains multiple scenes that can be opened after recognition
• you get a collection-level CollectionApi first, then a scene-level SceneApi for the current scene
• the host page can actively control the scanning flow instead of only waiting passively for recognition results

How It Differs from an Image AR Collection

• In an Image AR collection, cloud recognition is also used by default at the "choose which scene to open" stage. The difference is that after entering a concrete scene, the flow still depends on that scene's own target image for tracked and lostTrack.
• A Basic AR/Gyroscope collection relies on matching against the cloud image library, which usually means "recognize a target, then open the corresponding scene".

So Basic AR/Gyroscope collections are better suited when:

• target images are not fixed and there are many of them
• business rules need to dynamically restrict which scenes can currently be recognized
• the host layer wants to explicitly start, stop, or resume scanning

Typical Flow

A common Basic AR/Gyroscope collection flow is:

1. open the collection
2. trigger ready and receive collectionInfo and CollectionApi
3. start cloud-recognition scanning
4. after a target is recognized, open the corresponding scene
5. trigger sceneReady
6. download assets, load the scene, and enter the experience
7. when needed, close the current scene and return to scanning

So compared with a single scene, there is an extra layer of "collection container + scene switching".

Key Events

The host page usually cares about at least the following events:

Collection Level

• ready
• sceneReady
• sceneDestroy

Current Scene Level

• downloadAssetProgress
• loadSceneEnd
• sceneStart
• error
• incompatibility

The currently opened Basic AR/Gyroscope scene no longer performs its own recognition scan. In effect, Basic AR/Gyroscope scenes inside a collection always enter after scanning has already been resolved.

How CollectionApi Helps in Cloud Recognition Collections

The most valuable methods are:

await api.startCloudar();
await api.stopCloudar();
await api.backToScan();
await api.openScene(sceneId);
await api.closeCurrentScene();

startCloudar()

Actively start cloud-recognition scanning.

Suitable when:

• the host layer has a "Start Scanning" button
• you want to show a branded landing page before scanning starts
• only part of the scenes should be scannable

stopCloudar()

Actively stop scanning.

Suitable when:

• the host layer needs to show an overlay, explanation, or guidance and pause recognition
• the page enters a non-scanning state

backToScan()

Return from the current scene to scanning mode.

Suitable when:

• there is a "Continue scanning the next target" button
• the experience requires multiple rounds of recognition
• users should switch repeatedly between different targets in the same collection

Common Integration Modes

Mode 1: Scan by Default, Then Enter a Scene After Recognition

Good for quick integration.

The host layer mainly listens for:

• ready
• sceneReady
• sceneStart
• error
• incompatibility

Mode 2: Host Buttons Drive the Scan Flow

For example:

iframe.addEventListener('ready', (event) => {
  const api = event.detail.api;

  startButton.addEventListener('click', async () => {
    await api.startCloudar();
  });
});

This mode works well when you want to combine the default workflow with branded UI on the host page.

Mode 3: Return to Scan from the Current Scene

backButton.addEventListener('click', async () => {
  await collectionApi.backToScan();
});

This is ideal for "recognize one target -> browse the content -> go back and continue scanning".

Gyroscope

If Basic AR/Gyroscope scenes enable the gyroscope, permission handling and compatibility become more complex.

This issue is usually more noticeable in Basic AR/Gyroscope collections because:

• multiple scenes in the same collection may all depend on the gyroscope
• compatibility risk is higher on iOS and in-app WebViews

For Web iframe integrations, it is still recommended to disable gyroscope dependency whenever possible.

How to Organize Scanning and Scene Switching

A reliable host-layer pattern is usually:

1. save CollectionApi and collectionInfo at ready
2. update the current scene info and SceneApi at sceneReady
3. after entering a concrete scene, show buttons such as "Back to Scan" and "Next Target"
4. when the user clicks them, call backToScan() or openScene(sceneId)

Example:

let collectionApi = null;
let sceneApi = null;

iframe.addEventListener('ready', (event) => {
  collectionApi = event.detail.api;
});

iframe.addEventListener('sceneReady', (event) => {
  sceneApi = event.detail.api;
});

Suitable Business Cases

• campaign pages, treasure hunts, or check-in experiences with multiple recognizable targets
• multiple Basic AR/Gyroscope experiences organized under one entry point
• flows where the host page needs to customize scanning, return, and continue-recognition behavior

Integration Recommendations

1. Prefer handling "start scanning", "back to scan", and "stop scanning" through CollectionApi; do not mix those responsibilities into SceneApi.
2. Get the current scene's SceneApi only after sceneReady, and update that reference every time the scene changes.
3. If you need to limit recognition to only part of the targets, pass a subset scene list into startCloudar(collectionId, sceneList).
4. Add host-layer fallbacks for error and incompatibility, especially for camera and compatibility failures.
5. If your scenes include audio, video, or complex interactions, always cover iOS and your target in-app WebView in real-device regression testing.