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 concept and flow

Create

Create APIKeyAccessData using the cloud localization library appId, cloud service serverAddress, cloud service apiKey, and apiSecret from the configuration.

Then create MegaTrackerConfigs using the created APIKeyAccessData.

Next create SessionConfigs using MegaTrackerConfigs and the configured licenseKey.

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

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 create a session instance using configuration after obtaining megaComponent from the scene.

Caution

Single instance limitation: Only one session instance is allowed per scene. Before creating a new session, ensure that the old instance has been destroyed by calling closeSession(), otherwise creation will fail.

Start

Generally use the start(options) method of EasyARSession in the xr-frame AR system ready callback.

Warning

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

Register the AR system ready event using bind:ready="handleReady" in WXML:

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

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

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

Stop and destroy

Destroy the session using the closeSession() method of the EasyARMegaComponent attached in the xr-frame scene.

It is recommended to call this during 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();
    }
}

Foreground-background switching

Pause the session using the pause() method of EasyARSession when the page moves to the background. Resume the session using the resume() method of EasyARSession when the page returns to the foreground.

/** Mini-program page call */
onHide() {
    if (this.ar) {
        this.ar.pauseSession();
    }
},
onShow() {
    if (this.ar) {
        this.ar.resumeSession();
    }
}
/** Function in 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();
}

This code exposes two functions pauseSession() and resumeSession() in the xr-frame component.

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

Call resumeSession() in onShow when the mini-program moves from background to foreground to resume the session.