XR.requestSession()

The XR interface's requestSession() method returns a promise which resolves to an XRSession object through which you can manage the requested type of WebXR session.

While only one immersive VR session can be active at a time, multiple inline sessions can be in progress at once.

Syntax

var sessionPromise = xr.requestSession(sessionMode, sessionInit)

Parameters

 sessionMode
A DOMString whose value is one of those included in the XRSessionMode enum: either inline for an inline session or immersive-vr a fully-immersive virtual reality mode.
sessionInit Optional
A XRSessionInit object providing options to configure the new XRSession. See Specifying session options for details on how to configure a WebXR session.

Return value

A Promise that resolves with an XRSession object if the device and user agent support the requested mode and features.

Exceptions

This method doesn't throw true exceptions; instead, it rejects the returned promise, passing into it a DOMException whose name is one of the following:

InvalidStateError
The requested session mode is immersive-vr but there is already an immersive VR session either currently active or in the process of being set up. There can only be one immersive VR session at a time.
NotSupportedError
There is no WebXR-compatible device available, or the device does not support the specified sessionMode; this can also be thrown if any of the required options are unsupported.
SecurityError

Permission to enter the specified XR mode is denied. This can happen for a number of reasons, which are covered in more detail in Permissions and security in WebXR Device API.

Examples

Creating an immersive VR session

The following example calls requestSession() requesting an "immersive-vr" session. If the Promise resolves, it sets up a session and initiates the animation loop.

navigator.xr.requestSession("immersive-vr")
.then((xrSession) => {
  xrSession.addEventListener('end', onXRSessionEnded);
  // Do necessary session setup here.
  // Begin the session’s animation loop.
  xrSession.requestAnimationFrame(onXRAnimationFrame);
}).catch(function(error) {
  // "immersive-vr" sessions are not supported
  console.warn("'immersive-vr' isn't supported, or an error occurred activating VR!");
});

Verifying WebXR support and using a button to start VR mode

The following example shows how to use both isSessionSupported() and requestSession(). First, it checks to see if WebXR is available by verifying the existence of navigator.xr. Next, it calls isSessionSupported(), passing it the desired session option before enabling controls for entering XR. Adding controls is a necessary step because entering XR requires a user action. Finally, the onButtonClicked() method calls requestSession() using the same session option passed to isSessionSupported().

if (navigator.xr) {
  navigator.xr.isSessionSupported('immersive-vr')
  .then((isSupported) => {
    if (isSupported) {
      immersiveButton.addEventListener('click', onButtonClicked);
      immersiveButton.innerHTML = 'Enter XR';
      immersiveButton.disabled = false;
    } else {
      console.log("WebXR doesn't support immersive-vr mode!");
    }
  });
} else {
  console.log("WebXR is not available!");
}

function onButtonClicked() {
  if (!xrSession) {
    navigator.xr.requestSession('immersive-vr')
    .then((session) => {
      xrSession = session;
      // onSessionStarted() not shown for reasons of brevity and clarity.
      onSessionStarted(xrSession);
    });
  } else {
    // Button is a toggle button.
    xrSession.end().then(() => xrSession = null);
  }
}

Specifications

Specification Status Comment
WebXR Device API
The definition of 'XR.requestSession()' in that specification.
Working Draft Initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
requestSession()
ExperimentalNon-standard
Chrome No support NoEdge No support NoFirefox No support NoIE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support NoOpera Android No support NoSafari iOS No support NoSamsung Internet Android No support No

Legend

No support  
No support
Experimental. Expect behavior to change in the future.
Experimental. Expect behavior to change in the future.
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.