XRSystem.isSessionSupported() — Methode · JavaScript-Referenz

Signatur

XRSystem.prototype.isSessionSupported(mode)

Beschreibung

Die Methode isSessionSupported() des über navigator.xr erreichbaren XRSystem-Objekts prüft, ob ein bestimmter WebXR-Sitzungsmodus grundsätzlich verfügbar ist. Sie gibt ein Promise zurück, das mit true erfüllt wird, wenn der Modus unterstützt wird, und sonst mit false.

Typischerweise ruft man die Methode vor dem Anzeigen eines „VR starten“- oder „AR starten“-Buttons auf. So bekommen Nutzer nur Bedienelemente zu sehen, die auf ihrem Gerät auch funktionieren. Die eigentliche Sitzung startet man danach mit navigator.xr.requestSession(), und zwar innerhalb einer Nutzeraktion, etwa eines Klicks.

Wichtig: Ein true ist keine Garantie, dass requestSession() auch klappt. Der Nutzer kann die Berechtigung verweigern, angeforderte Features (requiredFeatures) können fehlen, oder das Gerät ist gerade nicht angeschlossen. Die Methode fragt keine Berechtigung ab und zeigt keinen Dialog an. Sie dient nur als leichte Vorabprüfung.

Parameter

Name	Typ	Default	Beschreibung
$mode Pflicht	"inline" \| "immersive-vr" \| "immersive-ar"		Der zu prüfende Sitzungsmodus: `inline` für eine Darstellung im Seitenelement, `immersive-vr` für exklusive VR auf einem Headset und `immersive-ar` für Augmented Reality, bei der Inhalte über die reale Umgebung gelegt werden.

Rückgabewert

Typ

Promise<boolean>

Beschreibung

Ein Promise, das mit true erfüllt wird, wenn der Modus unterstützt wird, und sonst mit false. Es wird mit einem SecurityError (DOMException) abgelehnt, wenn das Dokument WebXR nicht verwenden darf, zum Beispiel wegen einer Permissions Policy oder in einem nicht sicheren Kontext.

Beispiele

VR-Button nur bei Unterstützung anzeigen

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

const initVR = async () => {
  if (!navigator.xr) {
    vrButton.textContent = 'WebXR nicht verfügbar';
    vrButton.disabled = true;
    return;
  }
  const supported = await navigator.xr.isSessionSupported('immersive-vr');
  vrButton.hidden = !supported;
  console.log('immersive-vr unterstützt:', supported);
};

initVR();

immersive-vr unterstützt: true // z. B. auf einer Meta Quest

Alle Modi prüfen, mit Fehlerbehandlung

const modes = ['inline', 'immersive-vr', 'immersive-ar'];

const checkModes = async () => {
  if (!('xr' in navigator)) return {};
  const result = {};
  for (const mode of modes) {
    try {
      result[mode] = await navigator.xr.isSessionSupported(mode);
    } catch (err) {
      // z. B. SecurityError durch Permissions Policy
      console.warn(`${mode}: ${err.name}`);
      result[mode] = false;
    }
  }
  return result;
};

checkModes().then(console.log);

{ inline: true, immersive-vr: false, immersive-ar: true } // z. B. Chrome auf Android

Vorabprüfung und Sitzungsstart per Klick

const arButton = document.querySelector('#start-ar');

if (navigator.xr && await navigator.xr.isSessionSupported('immersive-ar')) {
  arButton.hidden = false;
  arButton.addEventListener('click', async () => {
    try {
      const session = await navigator.xr.requestSession('immersive-ar', {
        requiredFeatures: ['hit-test']
      });
      console.log('AR-Sitzung gestartet');
      session.addEventListener('end', () => console.log('AR-Sitzung beendet'));
    } catch (err) {
      // Trotz true kann der Start fehlschlagen (Feature fehlt, Nutzer lehnt ab)
      console.error('Start fehlgeschlagen:', err.name);
    }
  });
}

AR-Sitzung gestartet

// Wichtig · Fallstricke

Sicherer Kontext nötig: navigator.xr gibt es nur über HTTPS oder localhost. Prüfe vor dem Aufruf immer mit if (navigator.xr), ob die API vorhanden ist. Sonst gibt es einen TypeError.
Permissions Policy: In einem <iframe> muss die Direktive xr-spatial-tracking erlaubt sein, etwa mit allow="xr-spatial-tracking". Andernfalls wird das Promise mit einem SecurityError abgelehnt. Fange den Fehler deshalb immer ab.
Keine Garantie: true bedeutet nicht, dass requestSession() gelingt. Behandle Fehler beim Sitzungsstart trotzdem, und fordere optionale Features lieber über optionalFeatures an.
Datenschutz: Manche Browser antworten absichtlich ungenau, um Fingerprinting zu erschweren. Außerdem kann sich das Ergebnis ändern, wenn ein Headset an- oder abgesteckt wird. Das Event devicechange auf navigator.xr meldet solche Änderungen.
Browser-Unterstützung: Die Methode ist in Chromium-Browsern und im Meta-Quest-Browser verfügbar. Firefox und Safari auf dem Desktop unterstützen WebXR nicht. Safari auf der Apple Vision Pro unterstützt immersive-vr. Die Methode ersetzt das veraltete supportsSession() aus frühen Entwürfen, das ein abgelehntes Promise statt false lieferte.

Siehe auch

XRSystem XRSystem.requestSession() XRSession Navigator.xr FileSystemWritableFileStream.write()