XRSystem.requestSession() — Methode · JavaScript-Referenz

Signatur

XRSystem.prototype.requestSession(mode, options)

Beschreibung

navigator.xr.requestSession() ist der Einstieg in jede WebXR-Anwendung. Damit startest du eine Sitzung in einem von drei Modi: "inline" (Darstellung im normalen Seitenelement), "immersive-vr" (Vollbild-VR auf einem Headset) oder "immersive-ar" (Augmented Reality mit Durchsicht auf die reale Umgebung). Das zurückgegebene XRSession-Objekt steuert die Render-Schleife, die Eingabegeräte und die Referenzräume.

Immersive Sitzungen dürfen nur als Reaktion auf eine Nutzeraktivierung angefordert werden, also z. B. in einem click-Handler. Außerdem kann pro Dokument immer nur eine immersive Sitzung aktiv sein. Prüfe vorher mit XRSystem.isSessionSupported(), ob der gewünschte Modus überhaupt verfügbar ist, und blende den „VR starten“-Button nur dann ein.

Über das Optionsobjekt forderst du Zusatzfunktionen (Features) an, etwa Referenzräume wie "local-floor" oder AR-Funktionen wie "hit-test", "dom-overlay" oder "anchors". Features in requiredFeatures müssen verfügbar sein, sonst schlägt die Anfrage fehl. Features in optionalFeatures werden aktiviert, wenn möglich, und sonst stillschweigend weggelassen.

Parameter

Name	Typ	Default	Beschreibung
$mode Pflicht	"inline" \| "immersive-vr" \| "immersive-ar"		Der gewünschte Sitzungsmodus (`XRSessionMode`).
$options	XRSessionInit	{}	Optionales Objekt mit den Feldern `requiredFeatures` (Array<string>), `optionalFeatures` (Array<string>) und, je nach Feature, weiteren Einträgen wie `domOverlay: { root: Element }`.

Rückgabewert

Typ

Promise<XRSession>

Beschreibung

Ein Promise, das mit der neuen XRSession erfüllt wird. Es wird abgelehnt mit NotSupportedError (Modus oder Pflicht-Feature nicht verfügbar, Berechtigung verweigert), InvalidStateError (es läuft bereits eine immersive Sitzung) oder SecurityError (keine Nutzeraktivierung, unsicherer Kontext, Permissions-Policy blockiert).

Beispiele

VR-Sitzung per Button starten

const button = document.querySelector('#enter-vr');

const init = async () => {
  if (!navigator.xr) return;
  const supported = await navigator.xr.isSessionSupported('immersive-vr');
  button.hidden = !supported;
};

button.addEventListener('click', async () => {
  try {
    const session = await navigator.xr.requestSession('immersive-vr', {
      optionalFeatures: ['local-floor', 'bounded-floor']
    });
    console.log('Sitzung gestartet:', session.environmentBlendMode);
    session.addEventListener('end', () => console.log('Sitzung beendet'));
  } catch (err) {
    console.error(`${err.name}: ${err.message}`);
  }
});

init();

Sitzung gestartet: opaque

AR-Sitzung mit Hit-Test und DOM-Overlay

const startAR = async () => {
  const overlay = document.querySelector('#ar-ui');
  const session = await navigator.xr.requestSession('immersive-ar', {
    requiredFeatures: ['hit-test'],
    optionalFeatures: ['dom-overlay', 'local-floor'],
    domOverlay: { root: overlay }
  });

  // Welche optionalen Features wurden tatsächlich gewährt?
  console.log([...(session.enabledFeatures ?? [])]);
  return session;
};

document.querySelector('#start-ar').addEventListener('click', startAR);

["viewer", "local", "hit-test", "dom-overlay", "local-floor"]

Sitzung mit WebGL verbinden und Render-Schleife starten

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2', { xrCompatible: true });

document.querySelector('#enter-vr').addEventListener('click', async () => {
  const session = await navigator.xr.requestSession('immersive-vr');
  await session.updateRenderState({ baseLayer: new XRWebGLLayer(session, gl) });
  const refSpace = await session.requestReferenceSpace('local');

  const onFrame = (time, frame) => {
    const pose = frame.getViewerPose(refSpace);
    if (pose) {
      gl.bindFramebuffer(gl.FRAMEBUFFER, session.renderState.baseLayer.framebuffer);
      gl.clearColor(0.1, 0.2, 0.4, 1);
      gl.clear(gl.COLOR_BUFFER_BIT);
    }
    session.requestAnimationFrame(onFrame);
  };
  session.requestAnimationFrame(onFrame);
});

// Wichtig · Fallstricke

Nur in sicheren Kontexten (HTTPS oder localhost) verfügbar. In iframes muss die Permissions-Policy xr-spatial-tracking erlaubt sein, etwa über <iframe allow="xr-spatial-tracking">.
Immersive Modi brauchen eine Nutzeraktivierung. Ein Aufruf beim Laden der Seite führt zu einem SecurityError. Zwischen Klick und Aufruf keine langen await-Ketten einbauen, sonst kann die Aktivierung verfallen.
Es ist immer nur eine immersive Sitzung gleichzeitig möglich. Vor einem Neustart die alte Sitzung mit session.end() beenden, sonst folgt ein InvalidStateError.
Der Browser kann eine Berechtigungsabfrage anzeigen, etwa für Kamera oder Tracking. Lehnt der Nutzer ab, wird das Promise abgelehnt.
Kompatibilität: Unterstützt in Chrome/Edge (Desktop mit OpenXR, Android mit ARCore), im Meta-Quest-Browser und in Samsung Internet. Firefox und Safari auf dem Desktop unterstützen WebXR nicht. Safari auf visionOS unterstützt immersive-vr. Prüfe immer zuerst, ob navigator.xr existiert. Für ältere Browser gibt es den WebXR Polyfill.
Nicht erkannte Feature-Namen in requiredFeatures führen zum Fehlschlag. Nutze im Zweifel lieber optionalFeatures und prüfe danach session.enabledFeatures.

Siehe auch

XRSystem XRSystem.isSessionSupported() XRSession XRSession.requestReferenceSpace() XRSession.end() XRWebGLLayer FileSystemHandle.queryPermission()