FeaturePolicy — Schnittstelle · JavaScript-Referenz

Signatur

interface FeaturePolicy

Beschreibung

Über das Interface FeaturePolicy kann ein Skript abfragen, welche Browserfunktionen (z. B. camera, geolocation, fullscreen, autoplay) im aktuellen Ausführungskontext erlaubt sind. Die Richtlinien kommen aus dem HTTP-Header Feature-Policy bzw. Permissions-Policy und aus dem allow-Attribut eines <iframe>. Über das Interface lassen sie sich nur lesen, nicht ändern.

Man kommt auf zwei Wegen an eine Instanz: über document.featurePolicy für das aktuelle Dokument oder über iframeElement.featurePolicy für die Richtlinie, die ein eingebettetes Frame erhält. Einen öffentlichen Konstruktor gibt es nicht.

Diese Methoden stehen zur Verfügung:

allowsFeature(feature, origin?) gibt einen boolean zurück und sagt, ob die Funktion erlaubt ist, optional für einen bestimmten Ursprung.
features() gibt ein Array mit den Namen aller Funktionen zurück, die der Browser kennt.
allowedFeatures() gibt ein Array mit den Funktionen zurück, die im aktuellen Kontext erlaubt sind.
getAllowlistForFeature(feature) gibt die Ursprünge zurück, die die Funktion nutzen dürfen. ["*"] bedeutet: alle Ursprünge.

Das Interface eignet sich für Feature-Erkennung, bevor man eine Funktion nutzt, zum Beispiel um den Kamera-Button auszublenden, wenn camera gesperrt ist. Es hilft auch beim Debuggen von iframe-Einbettungen.

Parameter

Name	Typ	Default	Beschreibung
$feature Pflicht	string		Name der Funktion, z. B. `"camera"`, `"geolocation"` oder `"fullscreen"`. Wird von `allowsFeature()` und `getAllowlistForFeature()` verwendet.
$origin	string	Ursprung des Dokuments	Nur bei `allowsFeature()`: Ursprung, der geprüft werden soll, z. B. `"https://example.com"`. Ohne Angabe wird der Ursprung des aktuellen Dokuments geprüft.

Rückgabewert

Typ

FeaturePolicy

Beschreibung

Instanz, die über document.featurePolicy oder HTMLIFrameElement.featurePolicy abgerufen wird. Die Methoden geben boolean (allowsFeature) oder string[] (features, allowedFeatures, getAllowlistForFeature) zurück.

Beispiele

Instanz holen und erlaubte Funktionen auflisten

// Feature-Erkennung: nur Chromium stellt document.featurePolicy bereit
const policy = document.featurePolicy;

if (policy) {
  console.log('Bekannte Funktionen:', policy.features().length);
  console.log('Erlaubt:', policy.allowedFeatures());
} else {
  console.log('FeaturePolicy wird nicht unterstützt');
}

Bekannte Funktionen: 57 Erlaubt: ['accelerometer', 'autoplay', 'camera', 'fullscreen', ...]

Kamera-Button nur anzeigen, wenn die Funktion erlaubt ist

const cameraButton = document.querySelector('#start-camera');

const isAllowed = (feature) =>
  // Ohne API-Unterstützung optimistisch true annehmen
  document.featurePolicy?.allowsFeature(feature) ?? true;

if (!isAllowed('camera')) {
  cameraButton.hidden = true;
  console.warn('Kamera durch Permissions-Policy gesperrt');
} else {
  cameraButton.addEventListener('click', async () => {
    const stream = await navigator.mediaDevices.getUserMedia({ video: true });
    document.querySelector('video').srcObject = stream;
  });
}

Kamera durch Permissions-Policy gesperrt (bei Header: Permissions-Policy: camera=())

Richtlinie eines iframes und Allowlist prüfen

// HTML: <iframe id="map" src="https://maps.example.com" allow="geolocation; fullscreen"></iframe>
const frame = document.querySelector('#map');

if (frame.featurePolicy) {
  const fp = frame.featurePolicy;
  console.log('Geolocation im iframe:', fp.allowsFeature('geolocation'));
  console.log('Kamera im iframe:', fp.allowsFeature('camera'));
  console.log('Allowlist fullscreen:', fp.getAllowlistForFeature('fullscreen'));
}

// Für einen bestimmten Ursprung im Hauptdokument prüfen
console.log(
  document.featurePolicy?.allowsFeature('geolocation', 'https://maps.example.com')
);

Geolocation im iframe: true Kamera im iframe: false Allowlist fullscreen: ['https://maps.example.com'] true

// Wichtig · Fallstricke

Experimentell und kein Standard: Nur Chromium-Browser haben document.featurePolicy und HTMLIFrameElement.featurePolicy. Firefox und Safari haben sie nicht. Prüfen Sie deshalb immer vorher, ob die API vorhanden ist, z. B. mit document.featurePolicy?..
Umbenennung: Die Spezifikation heißt inzwischen Permissions Policy, der Header Feature-Policy wurde durch Permissions-Policy ersetzt, mit anderer Syntax: camera=(self) statt camera 'self'. Die JavaScript-Schnittstelle trägt in Chromium weiterhin den alten Namen, das kann sich aber ändern.
Erlaubt heißt nicht gewährt: Liefert allowsFeature('camera') den Wert true, hat der Nutzer die Berechtigung damit noch nicht erteilt. Den Berechtigungsstatus fragen Sie mit navigator.permissions.query() ab.
Das Interface ist schreibgeschützt. Richtlinien können nur über HTTP-Header oder das allow-Attribut gesetzt werden. Wird das allow-Attribut geändert, wirkt das erst, wenn das iframe neu geladen wird.
Die Namen der Funktionen hängen vom Browser ab. Nutzen Sie features(), statt sich auf eine feste Liste zu verlassen.
Sicherheit: Die Abfrage ist nur ein Hilfsmittel für die Oberfläche. Den eigentlichen Schutz setzt der Browser selbst durch, deshalb bringt eine clientseitige Prüfung allein keine zusätzliche Sicherheit.

Siehe auch

Permissions.query() CrashReport GestureEvent TextMetrics TextTrackList