Navigator.userActivation — Eigenschaft · JavaScript-Referenz

Signatur

get Navigator.userActivation

Beschreibung

Die schreibgeschützte Eigenschaft navigator.userActivation liefert ein UserActivation-Objekt. Darüber lässt sich der Benutzeraktivierungszustand des aktuellen Fensters abfragen. Viele Browser-Funktionen setzen eine solche Aktivierung voraus, zum Beispiel element.requestFullscreen(), window.open(), das Abspielen von Audio mit Ton, navigator.clipboard.writeText() oder navigator.vibrate().

Das Objekt hat zwei boolesche Eigenschaften:

hasBeenActive: Sticky Activation. Ist true, sobald der Benutzer die Seite seit dem Laden mindestens einmal aktiviert hat, etwa durch Klick, Tastendruck oder Touch. Der Wert bleibt danach dauerhaft true.
isActive: Transient Activation. Ist true nur kurz nach einer Aktivierung, also innerhalb eines vom Browser festgelegten Zeitfensters von einigen Sekunden. Manche APIs verbrauchen diese Aktivierung, zum Beispiel window.open().

Die Eigenschaft ist praktisch, um vorab zu prüfen, ob ein aktivierungspflichtiger API-Aufruf überhaupt klappen kann. So kann man z. B. eine Fehlermeldung vermeiden oder erst einen „Klicken zum Starten“-Hinweis anzeigen. Das ist auch in iframes und bei per postMessage() empfangenen Nachrichten nützlich: Dort kann man prüfen, ob der Aufruf wirklich auf eine Benutzeraktion zurückgeht.

Wichtig: Das zurückgegebene Objekt ist live. Seine Eigenschaften spiegeln immer den aktuellen Zustand wider. Man kann also eine Referenz speichern und später erneut abfragen.

Rückgabewert

Typ

UserActivation

Beschreibung

Ein live aktualisiertes UserActivation-Objekt mit den booleschen Eigenschaften hasBeenActive und isActive.

Beispiele

Aktivierungszustand abfragen

const activation = navigator.userActivation;

console.log('Schon einmal aktiv:', activation.hasBeenActive);
console.log('Gerade aktiv:', activation.isActive);

// Nach einem Klick erneut prüfen – das Objekt ist live
document.addEventListener('click', () => {
  console.log('Nach Klick:', activation.hasBeenActive, activation.isActive);
}, { once: true });

Schon einmal aktiv: false Gerade aktiv: false Nach Klick: true true

Autoplay mit Ton nur nach Benutzerinteraktion

const video = document.querySelector('video');
const hint = document.querySelector('#play-hint');

const startPlayback = async () => {
  if (!navigator.userActivation?.hasBeenActive) {
    // Noch keine Interaktion: stumm starten und Hinweis zeigen
    video.muted = true;
    hint.hidden = false;
  } else {
    video.muted = false;
  }
  try {
    await video.play();
  } catch (err) {
    console.warn('Wiedergabe blockiert:', err.name);
  }
};

startPlayback();

Popup nur öffnen, wenn eine transiente Aktivierung vorliegt

const openHelp = () => {
  if (navigator.userActivation?.isActive) {
    window.open('/hilfe', 'hilfe', 'width=600,height=400');
  } else {
    console.log('Kein Popup ohne direkte Benutzeraktion – zeige Inline-Hilfe.');
    document.querySelector('#inline-help').hidden = false;
  }
};

// Direkt nach Klick: isActive === true
document.querySelector('#help-btn').addEventListener('click', openHelp);

// Verzögert nach 10 s: Aktivierung ist meist abgelaufen
setTimeout(openHelp, 10_000);

Kein Popup ohne direkte Benutzeraktion – zeige Inline-Hilfe.

// Wichtig · Fallstricke

Browser-Unterstützung: Chromium-Browser ab Version 72, Firefox ab 120, Safari ab 16.4. In älteren Browsern ist die Eigenschaft undefined. Deshalb mit optionaler Verkettung prüfen: navigator.userActivation?.isActive.
Kurzes Zeitfenster: isActive gilt nur für ein kurzes, vom Browser festgelegtes Zeitfenster (meist etwa 5 Sekunden). Nach await-Ketten oder langen Netzwerkanfragen kann die Aktivierung schon abgelaufen sein.
Verbrauchende APIs: Manche APIs setzen isActive nach dem Aufruf sofort auf false, zum Beispiel window.open() oder requestFullscreen() in einigen Browsern. Ein zweiter Aufruf im selben Klick-Handler kann dann fehlschlagen.
Nicht jede Eingabe zählt: Nur „aktivierende“ Ereignisse lösen eine Benutzeraktivierung aus, etwa keydown (außer Esc und manchen Modifikatortasten), mousedown, pointerdown (Maus), pointerup und touchend. Scrollen oder mousemove zählen nicht.
Sicherheit: Die Eigenschaft ist schreibgeschützt, Skripte können keine Aktivierung vortäuschen. Mit dispatchEvent() ausgelöste, synthetische Ereignisse (isTrusted === false) erzeugen keine Aktivierung.
In Workern steht navigator.userActivation nicht zur Verfügung, nur im Fensterkontext.

Siehe auch

Navigator window.open() NavigateEvent.userInitiated Navigator.presentation Navigator.geolocation