Basic AR/Gyroscope

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

How It Differs from Image AR

• Image AR depends on a local target image, and the 3D content appears on top of that tracked image.
• Basic AR/Gyroscope relies on a large-scale cloud image database, and the 3D content appears directly on screen, optionally with gyroscope support.

In practice, Basic AR/Gyroscope can either skip the scan step or require scanning, while Image AR must scan before the experience can begin.

Typical Flow

1. open the scene
2. download assets
3. load the scene
4. wait for cloud recognition to match the target
5. enter the experience

If the Basic AR/Gyroscope scene is configured to skip cloud recognition, the flow becomes shorter.

Skip Cloud Recognition

The advanced API currently provides:

await api.skipCloudar();

This method:

1. stops cloud-recognition scanning
2. immediately enters the next step of the experience

In other words, it is effectively "skip waiting for scan results and enter the experience directly".

Suitable Use Cases

• you already completed your own recognition or pre-check flow on the host page
• you want users to click "Skip scan and preview directly", or to auto-skip after a timeout
• you need to enter the content quickly for certain operational flows
• the scene editor requires recognition, but some dynamic business condition allows skipping cloud recognition

Example

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

  skipButton.addEventListener('click', async () => {
    await api.skipCloudar();
  });
});

Notes

• This method only works for Basic AR/Gyroscope scenes.
• If the current scene is already configured to skip scanning, calling it does not provide any extra effect.
• It is better to expose "skip scan" as an explicit user action instead of triggering it automatically by default, otherwise you weaken the intended experience design of Basic AR/Gyroscope content.

Gyroscope

If a Basic AR/Gyroscope scene enables the gyroscope, additional motion logic is introduced after loading completes.

That causes two practical issues:

• the permission chain becomes more complex
• compatibility risk becomes higher on iOS and in-app WebViews

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

Recommended Host-Level Events

• ready
• downloadAssetProgress
• loadSceneEnd
• sceneStart
• error
• incompatibility

Suitable Business Cases

• scenes that need to match against a cloud image database, including large-scale image libraries
• campaigns where users cannot be given a fixed target image in advance, such as treasure hunts
• experiences where content should open only after recognition succeeds