Skip to main content
Version: 14 Oct 2024

Magic Leap WebXR Device API Support

Magic Leap offers support for WebXR Device API, allowing developers to build immersive augmented reality (AR) and virtual reality (VR) experiences. The API is pre-installed on Magic Leap devices and works with standard WebXR applications without additional configuration.

WebXR Viewer has been replaced with the System Web Browser

WebXR applications can be launched directly from the browser by manually entering a URL or by scanning a QR code with the QR Reader application.

Supported WebXR Features​

Magic Leap supports a wide range of WebXR specifications and extensions, as detailed below:

  • WebXR core/device API: Provides functionality for accessing immersive XR experiences on Magic Leap.
  • WebXR reference spaces: Includes viewer, local, local-floor, bounded-floor, and unbounded reference spaces.
  • Hand Tracking: Tracks hand positions for interaction with virtual objects.
  • Input Controller: Provides support for controller input in immersive experiences.
  • Hit Test: Enables placing virtual objects in the real world by detecting surfaces in the physical environment.
  • Plane Tracking: Detects and tracks planes in the user's environment for interaction.
  • Raw Camera Access: Allows access to raw, undistorted images from the RGB camera for computer vision tasks or image processing.
  • WebXR Layers: Currently support WebXR Projection and Quad layers only. (Multi Layered WebXR application currently will cause significantly lower frame rate.)

In addition, Magic Leap supports Global Dimming during the requestSession API in WebXR. Using immersive-vr will darken the real-world environment, while immersive-ar allows blending virtual and real-world content.

How To Enable Segmented Dimming™

Users can choose to use Segmented Dimming when using the web browser. Dimming can be enabled by performing the following steps:

  1. Open the System Web Browser
  2. Select the settings icon (⋮) from the top right-hand corner
  3. Select Browser Dimming
  4. Then enable Segmented Dimming™ feature for Browser

WebXR Raw Camera Access Module​

Magic Leap now includes support for the WebXR Raw Camera Access Module. This module allows developers to access raw, undistorted images from the headset’s RGB camera. This module is ideal for applications that require raw camera input for computer vision tasks, scene analysis, or image processing.

Simple Example​

To enable raw camera access in your WebXR application, the camera-access feature must be specified when requesting a WebXR session. Below is an example of how to enable camera access and handle raw frames:

// Request an immersive AR session with raw camera access
navigator.xr.requestSession('immersive-ar', {
  requiredFeatures: ['camera-access'],
  optionalFeatures: ['local-floor', 'bounded-floor']
}).then((session) => {
  // Request camera access and handle raw camera frames
  session.requestCameraAccess({
    onFrame: (cameraFrame) => {
      // Process the raw undistorted camera frame
      console.log('Received raw camera frame:', cameraFrame);
    }
  });
}).catch(err => {
  console.error('Failed to access raw camera frames:', err);
});

Testing Raw Camera Access​

You can test raw camera access functionality using the following Camera Access Barebones Example.

For more information on how to configure raw camera access, refer to the WebXR Raw Camera Access documentation.

Reference Spaces in WebXR​

Magic Leap supports multiple WebXR reference spaces, which define the coordinate systems used in immersive applications. The following reference spaces are available:

  • Viewer: View locked, origin inside the headset at all times, content will move with the view.
  • Local: World locked, origin at application startup head pose position.
  • Local-floor: World locked, origin at floor level.
  • Bounded-floor: The origin of a bounded-floor reference space will be initialized at a position on the floor
  • Unbounded: Places the origin at headset startup head pose position, or re-localized position.

The viewer and local spaces are enabled by default, while others require explicit inclusion in the session request. Here’s an example of setting up a local-floor reference space:

navigator.xr.requestSession('immersive-ar', {
  requiredFeatures: ['local-floor']
}).then(session => {
  // Request the local-floor reference space
  session.requestReferenceSpace('local-floor').then(refSpace => {
    console.log('Local-floor reference space enabled.');
  }).catch(err => {
    console.error('Error enabling reference space:', err);
  });
});

Permissions Handling​

WebXR requires user permission to start immersive AR or VR sessions. When a user visits a WebXR-enabled webpage, a prompt requests permission to enter immersive mode, ensuring user control and security.

For specific features like camera access, additional permissions must be requested during session setup. These features are enabled by specifying them in the requiredFeatures or optionalFeatures fields of the session request. Users will be prompted to approve access to these resources before the session begins

This permission process is part of the WebXR specification and cannot be bypassed.

Launching WebXR Applications​

Magic Leap does not support pinning web applications from the browser to the home menu. However, Magic Leap 2 provides alternative ways to quickly launch your WebXR application.

From APKs​

Developers can use Android Package Kits (APKs) that open a specified URL on startup. APKs can launch immersive web content via Custom Tabs or Trusted Web Activities.

Web Converter

You can use the Web Converter Tool to create an apk from a website url. To learn more see the Web Converter Guide for more information.

From QR Codes​

WebXR applications can be launched via QR codes, allowing users to scan a code and immediately open the URL in the Magic Leap browser. You can scan the QR code using the System QR Reader app or by selecting the QR Code icon next to the URL input field inside the Web Browser.

From the Browser​

WebXR applications can be launched directly from the Magic Leap browser by manually entering the application URL.

Detecting Magic Leap 2 Devices​

While WebXR provides APIs to identify devices, you may want to identify the device before starting your WebXR application to verify compatibility. One way to do this is to use the SEC-CH-UA-MODEL ID, which is a header that indicates the model of the device. For the Magic Leap 2, the value of this header is "Magic Leap 2". You can use this value to detect if the user is using a Magic Leap 2 device and provide them with a tailored web experience.

For example, you can use the following JavaScript code to check the value of the SEC-CH-UA-MODEL header:

// Function to detect if the user is using a Magic Leap 2 device
function detectMagicLeap2() {
  // Fetch the root document with the hint to receive the 'Sec-CH-UA-Model' header
  fetch("/", {
    headers: {
      "Sec-Fetch-Site": "same-origin",
      "Accept-CH": "Sec-CH-UA-Model" // Correctly request to receive the device model
    }
  })
  .then(response => {
    // Retrieve the 'Sec-CH-UA-Model' header from the response
    const model = response.headers.get("sec-ch-ua-model");
    if (model) {
      // Compare the model string to the target device
      if (model === "Magic Leap 2") {
        console.log("You are using a Magic Leap 2 device!");
        // Optionally, invoke any Magic Leap 2 specific code here
      } else {
        console.log("You are using a different device:", model);
        // Optionally, handle other devices here
      }
    } else {
      console.warn("The SEC-CH-UA-MODEL header is not available. Ensure the header is properly requested and accessible.");
    }
  })
  .catch(error => {
    // Handle potential errors from the fetch operation
    console.error("Error detecting the device:", error);
  });
}

// Invoke the function to perform the device detection
detectMagicLeap2();

For more information on how to use the Sec-CH-UA-Model header and other client hints, you can refer to the following resources:

Exiting WebXR Immersive Mode​

Users can exit a WebXR immersive session by pressing the menu button on the Magic Leap controller. This will close the session and return the user to a standard browser view.

Resources for New Developers​

If you are new to WebXR consider reviewing the following resources to help you get started:

WebXR Testing and Samples​

You can explore WebXR samples and testing tools at the following locations:

For additional guidance and best practices for developing immersive AR/VR experiences, refer to the official WebXR Developer Guide.