Getting Started with WebXR PWAs

Updated: Feb 6, 2025

Before you start packaging your WebXR experience as a PWA, we strongly recommend testing in Browser. PWAs run using the same rendering engine as Browser. This provides an easy way to identify any compatibility or performance issues with minimal effort.

You can find basic information about Browser, including the User Agent string, supported content sizes, and more in our Browser Getting Started guide. You can also connect the Chrome Developer Tools from your computer to a Meta Quest device for debugging and performance analysis using the Android Platform Tools.

Request WebXR Session after page load

We want WebXR PWAs to behave just like native immersive apps in Meta Horizon OS. This means the apps would jump into immersive right after launch without any 2D landing page. To do that, your WebXR app would need to call the requestSession API right after the page is loaded.

In THREE.js

Add a navigator.xr.requestSession call after the page initialization is finished.

For example, in init.js, at the end of the init function definition:

export async function init(setupScene = () => {}, onFrame = () => {}) {
  // Other setup code...
  if (navigator.xr && navigator.xr.isSessionSupported) {
    navigator.xr.isSessionSupported('immersive-vr').then((supported) => {
      if (supported && navigator.xr.requestSession) {
        navigator.xr.requestSession('immersive-vr', {
          optionalFeatures: ['REQUIRED_FEATURES'],
        })
        .then((session) => {renderer.xr.setSession(session);});
      }
    });
  }
}

In A-Frame

Add an event listener to the HTML file of your landing page.

For example:

<script type="text/javascript">
    const scene = document.querySelector('a-scene');
    if (scene.hasLoaded) {
        run();
    } else {
        scene.addEventListener('renderstart', run);
    }
    function run() {
        scene.enterVR();
    }
</script>

Create Your Web App Manifest

All PWAs need a Web App Manifest file. If your website already has one, or if it’s already set up as a PWA for other platforms, please review the steps below for Meta Quest specific manifest fields.

The following steps describe how to create a Web App Manifest:

Create a file named “manifest.webmanifest”, and copy the following contents to the file:

{
  "short_name": "PWA Name",
  "name": "Full name of your PWA",
  "icons": [
 {
   "src": "/images/icons-192.png",
   "type": "image/png",
   "sizes": "192x192"
 },
 {
   "src": "/images/icons-512.png",
   "type": "image/png",
   "sizes": "512x512"
 }
  ],
  "start_url": "https://domain.com/startpage/",
  "scope": "https://domain.com/",
}

Populate the manifest using the following supported Web App Manifest fields:

Name	Required / Optional	Description
`name`	Required	The name of your PWA. Currently we only support left-to-right languages for the name.
`short_name`	Optional	A shorter version of the app name, if needed.
`start_url`	Optional	You can specify a starting URL to load. If not provided, this will be derived from the `web-manifest-url`. The start page for your PWA should provide direct access to your App’s functionality or a login screen that proceeds to your App’s functionality. It should not be a marketing or information page. At least one of the `start_url` and `web-manifest-url` must be provided (both cannot be missing).
`scope`	Optional	This field allows you to specify what URL or paths should be considered as part of your app. It’s not required and you don’t need to put a value unless you have specific requirements, such as excluding portions of your website from your PWA. If not provided, this will be derived from the `start_url` field or the `web-manifest-url` parameter (whichever is provided, see information on those fields).
`icons`	Optional	It is used to specify one or more image files that define the icons to represent your web application. The icon image is going to be used by the UI bar in Meta Horizon OS.

All other fields are not currently supported and are ignored.

Scope and Scope Extensions

PWA Scope determines what URLs are treated as “part of the web app” and which are not. Out-of-scope links within the WebXR PWA will be opened in the regular browser. This is often used for cases where a user needs to briefly navigate to an external site, such as an OAuth or other external login page.

Frequently Asked Questions

What are the user activation requirements for `requestSession` API?

The XRSystem:requestSession() method requires a user activation as a security check before a WebXR session can be created. This prevents the user from being brought into an immersive WebXR session right after a WebXR page is loaded in the regular browser. In the WebXR PWA scenario, we treat the PWA app icon click as the user action to create a WebXR session for PWAs. It provides the same user experience as other immersive apps in Meta Horizon OS.

Can I call `requestSession` after the page load only in a PWA?

Yes. You can check whether the Digital Goods service is available before calling requestSession to make sure you are under a PWA scope.

if (window.getDigitalGoodsService !== undefined) {
  // Add your requestSession related logic here
}

How to debug WebXR PWAs on Quest devices?

You can connect the Chrome Developer Tools from your computer to a Meta Quest device for debugging. You will be able to see your website tab being loaded in chrome://inspect after your WebXR PWA is launched. Click inspect to start debugging that tab in Browser.

Did you find this page helpful?