Known issues and limitations of the WeChat Mini Program Mega plugin

This article introduces the known issues and limitations when using the Mega Mini Program plugin.

Known issues in WeChat

Currently confirmed defects in WeChat xr-frame or VisionKit. When occurring, it will cause AR functions to fail. Please pay attention to related triggering scenarios during development.

Wechat plane detection exception

In certain situations (such as when a large white wall appears in the frame or the camera is blocked for an extended period), the plane detection provided by WeChat may exhibit abnormal status. In this state, MegaTracker cannot function properly.

For handling methods, refer to Plane AR tracker exception handling.

Session initialization takes a long time

The AR Session needs to wait for the WeChat plane detection initialization to complete before it can finish initialization. In some cases, the WeChat plane detection initialization takes a long time.

The reason why the AR Session needs to wait for the xr-frame ARTracker initialization to complete can be found in How MegaTracker works on xr-frame.

Status reference: WeChat Mini Program AR Tracker status documentation.
Listening 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.');
    }
}

The worldPosition of the node will not be updated immediately in the current frame

In this example, trs.worldPosition is not updated in time:

public onTick(delta, data) {
    const trs = this.el.getComponent(xrFrameSystem.Transform);
    // WorldPosition of the node before update  
    console.log(`World Position before update: ${trs.worldPosition.x}, ${trs.worldPosition.y}, ${trs.worldPosition.z}`);
    // LocalPosition of the node before update  
    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;
    // The WorldPosition of the node is not updated  
    console.log(`World Position after update: ${trs.worldPosition.x}, ${trs.worldPosition.y}, ${trs.worldPosition.z}`);
    // The LocalPosition of the node is updated  
    console.log(`Local Position after update: ${trs.Position.x}, ${trs.Position.y}, ${trs.Position.z}`);
}

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

Screen orientation switching exception

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

When the device exits the Mini Program in landscape mode and re-enters in portrait mode, the AR display may appear abnormal.

Therefore, never use "auto" in AR Mini Program applications.

Usage limitations

Hard requirements for feature operation. When not met, the feature is unavailable, but can be avoided by adjusting configuration or environment.

Device restrictions

Devices running the Mega mini-program plugin must support at least WeChat VisionKit V1 plane interface. For optimal performance, it is recommended to use devices that support WeChat VisionKit V2 plane interface.

List of supported devices: Refer to the 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 Interface > VisionKit visual capabilities > Horizontal plane AR-v2 to quickly determine whether the current device is supported.

If you need to use Mega services on devices that do not support VisionKit, refer to the navigation scenario best practices to use the View+ AR navigation product, which supports almost all devices.

PlaneMode mandatory configuration

Due to limitations in certain WeChat interface support, planeMode must be set to 1.

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

Gps function limitations

Currently does not support aligning blocks via GPS.

Currently does not support placing annotation data via GPS.

Table of Contents