Permissions API: Berechtigungen proaktiv abfragen

1. Das Problem mit blind ausgelösten Berechtigungsdialogen

Berechtigungsdialoge für Kamera, Mikrofon, Standort oder Benachrichtigungen sind mächtige, aber auch störende UI-Elemente, die der Browser selbst kontrolliert und die eine Anwendung nicht gestalterisch beeinflussen kann. Erscheint ein solcher Dialog ohne erkennbaren Grund direkt beim Laden der Seite, lehnen viele Nutzer ihn reflexartig ab, selbst wenn die Funktion später tatsächlich gebraucht würde.

Ein einmal abgelehnter Dialog lässt sich in den meisten Browsern nicht einfach erneut auslösen, der Nutzer muss die Berechtigung manuell in den Website-Einstellungen des Browsers zurücksetzen. Das macht eine unüberlegte, verfrühte Anfrage teuer: Die Funktion bleibt dauerhaft blockiert, bis der Nutzer selbst aktiv wird, was in der Praxis selten passiert. Diese Endgültigkeit unterscheidet Berechtigungsdialoge deutlich von anderen UI-Elementen wie Cookie-Bannern, bei denen ein erneuter Versuch meist folgenlos bleibt.

2. navigator.permissions.query() als Lösung

Die Permissions API erlaubt es, den aktuellen Status einer Berechtigung abzufragen, ohne den nutzerseitigen Dialog auszulösen. Der Aufruf navigator.permissions.query({ name: 'camera' }) gibt ein Promise zurück, das mit einem PermissionStatus-Objekt aufgelöst wird, dessen state-Eigenschaft einen von drei Werten annimmt: granted, denied oder prompt.

Mit diesen drei Zuständen lässt sich die Oberfläche gezielt vorbereiten: Bei granted kann die Funktion direkt aktiviert werden, bei denied zeigt man besser einen Hinweis mit Anleitung zur manuellen Freigabe statt eines wirkungslosen erneuten Dialogs, und bei prompt lohnt sich eine erklärende Vorabinformation, bevor der eigentliche Dialog erscheint.

async function checkCameraPermission() {
  try {
    const status = await navigator.permissions.query({ name: 'camera' });
    return status.state; // 'granted' | 'denied' | 'prompt'
  } catch (err) {
    // Manche Browser kennen 'camera' als Query-Namen nicht
    return 'unsupported';
  }
}

const state = await checkCameraPermission();
if (state === 'granted') {
  startVideoCall();
} else if (state === 'denied') {
  showManualEnableInstructions();
} else {
  showExplanationBeforeRequest();
}

3. Änderungen live mitverfolgen

Das PermissionStatus-Objekt bleibt nach der Abfrage aktiv und feuert ein change-Event, sobald sich der Status ändert, etwa weil der Nutzer die Berechtigung während der Sitzung manuell in den Browser-Einstellungen anpasst. Das erlaubt es, die Oberfläche in Echtzeit zu aktualisieren, ohne dass die Seite neu geladen werden muss.

Das ist besonders in länger laufenden Anwendungen wie Video-Konferenz-Tools relevant, bei denen ein Nutzer während eines Meetings die Kamera-Berechtigung widerruft. Ohne den change-Listener würde die Anwendung erst beim nächsten aktiven Kamera-Zugriff vom Entzug erfahren, mit dem Listener kann sofort reagiert und der Nutzer informiert werden.

const status = await navigator.permissions.query({ name: 'camera' });

status.addEventListener('change', () => {
  console.log('Neuer Berechtigungsstatus:', status.state);
  if (status.state !== 'granted') {
    pauseVideoCallAndNotifyUser();
  }
});

4. Welche Berechtigungsnamen unterstützt werden

Der Umfang der abfragbaren Berechtigungsnamen unterscheidet sich zwischen Browsern deutlich. Weit verbreitet und zuverlässig unterstützt sind unter anderem geolocation, notifications, camera, microphone, clipboard-read und clipboard-write, während exotischere Namen wie midi oder persistent-storage nicht überall verfügbar sind.

Da ein unbekannter Name in manchen Browsern zu einem abgelehnten Promise führt, sollte jeder Aufruf in einem Try-Catch-Block stehen, mit einem sinnvollen Fallback-Verhalten für den Fall, dass die Abfrage selbst fehlschlägt. Die Anwendung darf dann nicht blockieren, sondern sollte sich so verhalten, als wäre der Status unbekannt, und den regulären Berechtigungsfluss nutzen.

5. Ein bewährtes UX-Muster: Vorab-Erklärung

Ein wirkungsvolles Muster kombiniert die Statusabfrage mit einem eigenen, gestaltbaren Zwischenschritt: Bevor der native Dialog erscheint, zeigt die Anwendung eine eigene, gebrandete Erklärung, warum die Berechtigung gebraucht wird, mit einem klaren Call-to-Action-Button. Erst ein Klick auf diesen Button löst den eigentlichen getUserMedia()- oder getCurrentPosition()-Aufruf und damit den nativen Dialog aus.

Dieser Umweg über eine eigene UI wirkt zunächst wie ein zusätzlicher Schritt, erhöht aber nachweislich die Zustimmungsrate, weil der Nutzer den Kontext versteht, bevor der Browser-Dialog erscheint. Die Statusabfrage stellt dabei sicher, dass dieser Zwischenschritt nur gezeigt wird, wenn der Status tatsächlich prompt ist, und nicht bei bereits erteilter oder dauerhaft verweigerter Berechtigung.

async function requestCameraWithExplanation() {
  const status = await navigator.permissions.query({ name: 'camera' });

  if (status.state === 'granted') {
    return navigator.mediaDevices.getUserMedia({ video: true });
  }

  if (status.state === 'prompt') {
    const confirmed = await showCustomExplanationDialog(
      'Wir benötigen Zugriff auf deine Kamera für den Video-Call.'
    );
    if (!confirmed) return null;
  }

  // Bei 'denied' zeigt getUserMedia direkt einen Fehler, den man abfangen kann
  return navigator.mediaDevices.getUserMedia({ video: true });
}

6. Sonderfall Push-Benachrichtigungen

Bei Benachrichtigungen kommt zur Permissions API noch Notification.permission als zusätzliche, ältere Statusquelle hinzu, die synchron ausgelesen werden kann, während navigator.permissions.query({ name: 'notifications' }) asynchron arbeitet und in manchen Browsern feinere Zustandsänderungen erkennt. Für einfache Prüfungen genügt oft die synchrone Variante, für reaktives UI mit Live-Updates ist die Permissions API vorzuziehen.

Push-Benachrichtigungen sind zudem ein gutes Beispiel dafür, wie wichtig Timing ist: Eine Anfrage direkt nach dem ersten Seitenaufruf hat erfahrungsgemäß deutlich niedrigere Zustimmungsraten als eine Anfrage, die erst nach einer sinnvollen Nutzerinteraktion erscheint, etwa nachdem der Nutzer eine erste Bestellung erfolgreich abgeschlossen hat.

In der Praxis lohnt es sich, die Statusabfrage für Benachrichtigungen mit einem einfachen internen Zähler zu kombinieren, der protokolliert, wie oft ein Nutzer bereits mit der Anwendung interagiert hat, bevor überhaupt eine eigene Erklärung gezeigt wird. So lässt sich vermeiden, dass Erstbesucher, die die Seite noch gar nicht kennen, sofort mit einer Anfrage konfrontiert werden, die inhaltlich noch gar keinen Sinn für sie ergibt.

7. Grenzen der API

Die Permissions API kann selbst keine Berechtigung erteilen oder entziehen, sie ist ausschließlich ein Lesezugriff auf den aktuellen Zustand. Für das tatsächliche Anfordern bleibt weiterhin die jeweilige Feature-API zuständig, etwa getUserMedia() für Kamera und Mikrofon oder getCurrentPosition() für Standort.

Außerdem unterscheidet sich das Verhalten bei denied je nach Berechtigung: Manche Browser lösen bei einer bereits dauerhaft verweigerten Kamera-Berechtigung gar keinen neuen Dialog mehr aus, sondern lassen die Feature-API sofort mit einem Fehler fehlschlagen, weshalb die eigene Fehlerbehandlung robust gegenüber beiden Fällen sein muss.

Eine weitere Grenze betrifft die Granularität: Die API liefert einen groben Status für eine gesamte Berechtigungskategorie, kennt aber keine feineren Abstufungen, wie sie manche native Betriebssysteme anbieten, etwa eine zeitlich begrenzte Freigabe des Standorts nur für die Dauer der aktuellen Sitzung. Wer eine solche feinere Steuerung benötigt, muss sie auf Anwendungsebene selbst nachbilden, etwa indem man erteilte Berechtigungen nach einer gewissen Zeit im eigenen State wieder als unsicher behandelt und erneut nachfragt. Auch iframe-Kontexte verdienen besondere Aufmerksamkeit: Eingebettete Drittanbieter-Inhalte erben Berechtigungen nicht automatisch vom übergeordneten Dokument, weshalb eine Statusabfrage innerhalb eines iframes gesondert erfolgen und über eine passende Permissions-Policy im übergeordneten Dokument ausdrücklich erlaubt werden muss.

8. Browser-Unterstützung und Feature-Detection

Alle modernen Chromium-basierten Browser sowie Firefox unterstützen navigator.permissions.query() breit, Safari unterstützt einen Teil der Berechtigungsnamen, aber nicht alle. Vor dem Einsatz lohnt sich eine einfache Prüfung auf 'permissions' in navigator, kombiniert mit dem bereits erwähnten Try-Catch um den eigentlichen query()-Aufruf.

Fehlt die Unterstützung vollständig, verhält sich die Anwendung am robustesten, wenn sie einfach auf die klassische, direkte Anfrage über die jeweilige Feature-API zurückfällt, ohne die vorherige Statusprüfung. Der Nutzer sieht dann den regulären Dialog ohne die zusätzliche Vorab-Erklärung, verliert aber keine Kernfunktionalität.

9. Ein zentrales Utility für mehrere Berechtigungen

In größeren Anwendungen mit mehreren berechtigungspflichtigen Funktionen lohnt sich eine kleine zentrale Utility-Funktion, die Statusabfrage, Fehlerbehandlung und Change-Listener für beliebige Berechtigungsnamen kapselt. So bleibt der Aufruf an jeder Stelle der Anwendung konsistent und die Fallback-Logik muss nur an einer Stelle gepflegt werden.

Die folgende Tabelle vergleicht typische Berechtigungen hinsichtlich Support-Breite und empfohlener UX-Strategie, als praktische Orientierung für die eigene Implementierung.

async function getPermissionState(name) {
  if (!('permissions' in navigator)) return 'unsupported';
  try {
    const status = await navigator.permissions.query({ name });
    return status.state;
  } catch {
    return 'unsupported';
  }
}

async function watchPermission(name, onChange) {
  if (!('permissions' in navigator)) return;
  try {
    const status = await navigator.permissions.query({ name });
    onChange(status.state);
    status.addEventListener('change', () => onChange(status.state));
  } catch {
    onChange('unsupported');
  }
}

watchPermission('geolocation', (state) => {
  document.querySelector('#location-hint').hidden = state === 'granted';
});

10. Zusammenfassung

11. FAQ: Permissions API: Das Wichtigste auf einen Blick