Known issues and limitations of wechat mini program mega plugin

This article introduces known issues and limitations when using the Mega mini program plugin.

Known issues in wechat

Currently confirmed defects in WeChat xr-frame or VisionKit. Occurrence will cause AR functionality to fail. Please be aware of related trigger scenarios during development.

Abnormal plane detection in wechat

Under specific circumstances (such as large white walls appearing in the frame, prolonged camera obstruction, etc.), WeChat's plane detection may enter an abnormal state. In this state, MegaTracker cannot function properly.

Refer to Plane AR tracker exception handling for resolution methods.

Long session initialization time

The AR Session must wait for WeChat's plane detection initialization to complete. In some cases, WeChat plane detection initialization takes longer.

Reasons why AR Session must wait for xr-frame ARTracker initialization completion can be found in How MegaTracker works on xr-frame.

Status reference: WeChat Mini Program AR tracker status documentation.
Monitoring example:

<xr-ar-tracker id="xrARTracker" mode="Plane" bind:ar-tracker-state="handleARTrackerState"></xr-ar-tracker>

handleARTrackerState({detail}) {
    if (detail.value.state == xrFrameSystem.EARTrackerState.Detected) {
        console.log('Plane is now detected by XR-Frame ARTracker.');
    }
}

Node's worldPosition not updated immediately in current frame

In this example, trs.worldPosition is not updated promptly:

public onTick(delta, data) {
    const trs = this.el.getComponent(xrFrameSystem.Transform);
    // WorldPosition before updating this node
    console.log(`World Position before update: ${trs.worldPosition.x}, ${trs.worldPosition.y}, ${trs.worldPosition.z}`);
    // LocalPosition before updating this node
    console.log(`Local Position before update: ${trs.Position.x}, ${trs.Position.y}, ${trs.Position.z}`);
    trs.position.x += 0.1;
    trs.position.y += 0.1;
    trs.position.z += 0.1;
    // WorldPosition of this node not updated
    console.log(`World Position after update: ${trs.worldPosition.x}, ${trs.worldPosition.y}, ${trs.worldPosition.z}`);
    // LocalPosition of this node updated
    console.log(`Local Position after update: ${trs.Position.x}, ${trs.Position.y}, ${trs.Position.z}`);
}

During development, it's recommended to consistently use LocalTransform, i.e., el.getComponent(xrFrameSystem.Transform).position and el.getComponent(xrFrameSystem.Transform).rotation.

Abnormal screen orientation switching

If "auto" is set in the window section of the WeChat Mini Program global configuration app.json:

When the device exits the mini program in landscape mode and re-enters in portrait mode, abnormal AR display may occur.

Therefore, never use "auto" in AR mini program applications.

Usage limitations

Hard requirements for functionality operation. Functionality is unavailable when unmet, but can be avoided by adjusting configuration or environment.

Device limitations

Devices running the Mega mini program plugin must support at least WeChat VisionKit V1 plane interface. For optimal results, use devices supporting WeChat VisionKit V2 plane interface.

Supported device list: Refer to V2 plane AR interface support list.
Quick verification method:
1. Scan the official WeChat Mini Program Sample QR code.
2. After entering the mini program, navigate to Interfaces > VisionKit visual capabilities > Horizontal plane AR-v2 to quickly verify device compatibility.

To use Mega services on devices not supporting VisionKit, refer to Navigation scenario best practices to use Vision Plus AR Navigation product compatible with nearly all devices.

PlaneMode mandatory configuration

Limited by WeChat interface support, planeMode must be set to 1.

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

GPS functionality limitations

Currently does not support block alignment via GPS.

Currently does not support placing annotation data via GPS.

Table of Contents