AR session flow control

This document introduces AR session flow control, including how to create, start, stop, and destroy an AR session.

Before you begin

Understand AR Session concepts and workflow

Create

Use the cloud positioning library appId, cloud service serverAddress, cloud service apiKey, and apiSecret from the configuration to create APIKeyAccessData.

Then use the created APIKeyAccessData to create MegaTrackerConfigs.

Next, use MegaTrackerConfigs and the licenseKey from the configuration to create SessionConfigs.

Finally, use the createSession(sessionConfigs) method of the EasyARMegaComponent attached in the xr-frame scene to create the session.

createSession() {
    // Get the megaComponent attached in the scene
    const megaElement = scene.getElementById('easyar-mega');
    const megaComponent = megaElement.getComponent("easyar-mega") as easyar.EasyARMegaComponent;
    // MegaTracker cloud service authentication configuration
    const apiKeyAccess = new mega.APIKeyAccessData(this.data.appId, this.data.serverAddress, this.data.apiKey, this.data.apiSecret);
    const megaTrackerConfigs: easyar.MegaTrackerConfigs = {
        access: apiKeyAccess
    }
    // Session configuration
    const sessionConfigs: easyar.SessionConfigs = {
        megaTrackerConfigs: megaTrackerConfigs,
        licenseKey: settings.EasyARLicenseKey
    }
    // Create instance
    session = megaComponent.createSession(sessionConfigs);
}

This code demonstrates how to obtain the megaComponent from the scene and then use the configuration to create a session instance.

Caution

Single-instance restriction: Only one Session instance is allowed in a scene. Before creating a new Session, you must ensure that the old instance has been destroyed by calling closeSession(), otherwise the creation will fail.

Start

Generally, use the start(options) method of EasyARSession in the callback when the xr-frame AR system is ready to start the session.

Warning

MegaTracker relies on data provided by the plane AR tracker and cannot work before the plane tracker is initialized.

In WXML, use bind:ready="handleReady" to register the AR system ready event:

<xr-scene ar-system="modes:Plane; planeMode: 1" bind:ready="handleReady">

In the callback function handleReady in the xr-frame component, use the start(options) method of EasyARSession to start the session.

handleReady: function(event) {
    try {
        //Start the Session, default retry 5 times on failure
        await session.start();
    } catch (err) {
        console.error(`EasyAR Session initialization failed: ${err.message}`);
        return;
    }
}

Stop and destroy

Use the EasyARMegaComponent's closeSession() method mounted in the xr-frame scene to destroy the session.

It is recommended to call it in the detached lifecycle of the xr-frame component to ensure destruction when leaving the page (i.e., when the component instance is removed from the page node tree).

lifetimes: {
    detached: function() {
        const megaElement = scene.getElementById('easyar-mega');
        const megaComponent = megaElement.getComponent("easyar-mega") as easyar.EasyARMegaComponent;
        megaComponent.closeSession();
    }
}

Switching between foreground and background

When the page moves to the background, use the EasyARSession method pause() to pause the session.
When the page returns to the foreground, use the EasyARSession method resume() to resume the session.

/** Mini-program page calls */
onHide() {
    if (this.ar) {
        this.ar.pauseSession();
    }
},
onShow() {
    if (this.ar) {
        this.ar.resumeSession();
    }
}
/** Functions in the xr-frame component */
pauseSession(): void {
    if (!session) { console.error("EasyAR Session is not ready"); return;}
    session.pause();
},
resumeSession(): void {
    if (!session) { console.error("EasyAR Session is not ready"); return;}
    session.resume();
}

In this code, the xr-frame component exposes two functions: pauseSession() and resumeSession().

In the mini-program page, call pauseSession() in onHide (when the mini-program moves from the foreground to the background) to pause the session.

In onShow (when the mini-program moves from the background to the foreground), call resumeSession() to resume the session.

Table of Contents