The XRSystem
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 theXRSessionMode
enum
. The supported modes are:immersive-ar
-
The session's output will be given exclusive access to the immersive device, but the rendered content will be blended with the real-world environment. The session's
environmentBlendMode
indicates the method to be used to blend the content together.Important: The
immersive-ar
mode is defined by the WebXR Augmented Reality Module, which is not yet stable and should not be used other than for testing and experimentation. immersive-vr
- Indicates that the rendered session will be displayed using an immersive XR device in VR mode; it is not intended to be overlaid or integrated into the surrounding environment. The
environmentBlendMode
is expected to beopaque
if possible, but might beadditive
if the hardware requires it. inline
- The output is presented inline within the context of an element in a standard HTML document, rather than occupying the full visual space. Inline sessions can be presented in either mono or stereo mode, and may or may not have viewer tracking available. Inline sessions don't require special hardware and should be avalable on any user agent offering WebXR API support.
sessionInit
Optional- A
XRSessionInit
object providing options to configure the newXRSession
. 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 'requestSession()' in that specification. |
Working Draft | Initial definition. |
Browser compatibility
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
requestSession() | Chrome Full support 79 | Edge Full support 79 | Firefox No support No | IE No support No | Opera No support No | Safari No support No | WebView Android No support No | Chrome Android Full support 79 | Firefox Android No support No | Opera Android No support No | Safari iOS No support No | Samsung Internet Android Full support 11.2 |
Legend
- Full support
- Full support
- No support
- No support
- Experimental. Expect behavior to change in the future.
- Experimental. Expect behavior to change in the future.