UserActivation.hasBeenActive — Eigenschaft · JavaScript-Referenz

Signatur

navigator.userActivation.hasBeenActive

Beschreibung

Die Eigenschaft hasBeenActive des UserActivation-Objekts (erreichbar über navigator.userActivation) liefert true, sobald der Nutzer im aktuellen Fenster mindestens einmal eine aktivierende Interaktion ausgeführt hat. Dazu zählen zum Beispiel keydown (außer Escape und reinen Modifikatortasten), mousedown, pointerdown mit Maus, pointerup und touchend. Reines Scrollen, Hovern oder Fokuswechsel zählen nicht dazu.

Diese sogenannte sticky activation bleibt bestehen, bis die Seite neu geladen oder verlassen wird. Sie verfällt also nicht, das unterscheidet sie von der transienten Aktivierung, die UserActivation.isActive meldet und die nur ein paar Sekunden nach einer Interaktion gilt.

Einige Browser-APIs setzen eine sticky activation voraus, zum Beispiel die automatische Wiedergabe von Medien mit Ton oder die Rückfrage im beforeunload-Dialog. Mit hasBeenActive kannst du vorher prüfen, ob solche Aufrufe erlaubt sind. So kannst du einen passenden Hinweis zeigen, statt dass der Aufruf ohne Meldung scheitert. Auch in eingebetteten Frames nützt die Eigenschaft: Damit findest du heraus, ob der Nutzer schon mit dem Frame interagiert hat.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn im Fenster seit dem Laden schon eine aktivierende Nutzerinteraktion stattgefunden hat, sonst false.

Beispiele

Sticky activation prüfen

// Direkt nach dem Laden hat noch keine Interaktion stattgefunden
console.log(navigator.userActivation.hasBeenActive);

document.addEventListener('pointerup', () => {
  // Nach dem ersten Klick bleibt der Wert dauerhaft true
  console.log(navigator.userActivation.hasBeenActive);
}, { once: true });

false true

Video mit Ton erst nach der ersten Interaktion starten

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

const startVideo = async () => {
  if (navigator.userActivation?.hasBeenActive) {
    video.muted = false;
    await video.play();
    hint.hidden = true;
  } else {
    // Ohne Aktivierung ist Autoplay nur stumm erlaubt
    video.muted = true;
    await video.play();
    hint.hidden = false; // „Zum Aktivieren des Tons klicken“
  }
};

startVideo();
document.addEventListener('click', startVideo, { once: true });

Warnung vor ungespeicherten Änderungen

const form = document.querySelector('form');
let dirty = false;
form.addEventListener('input', () => { dirty = true; });

window.addEventListener('beforeunload', (event) => {
  // Ohne sticky activation zeigt der Browser den Dialog ohnehin nicht an
  if (dirty && navigator.userActivation.hasBeenActive) {
    event.preventDefault();
  }
});

Aktivierungsstatus mit Funktionsprüfung abfragen

const getActivationState = () => {
  if (!('userActivation' in navigator)) return 'unbekannt';
  const { hasBeenActive, isActive } = navigator.userActivation;
  return { hasBeenActive, isActive };
};

setTimeout(() => console.log(getActivationState()), 10000);

{ hasBeenActive: true, isActive: false } // wenn der Nutzer vor mehr als ~5 s geklickt hat

// Wichtig · Fallstricke

Schreibgeschützt: Du kannst den Wert nicht setzen. Eine Aktivierung lässt sich auch nicht künstlich auslösen, synthetische Ereignisse aus dispatchEvent() oder element.click() zählen nicht.
Kein Verbrauch: Anders als die transiente Aktivierung wird die sticky activation nicht durch APIs wie window.open() verbraucht. Sie gilt bis zum Neuladen oder Verlassen der Seite.
Frames: Der Wert gilt nur für das eigene Fenster und dessen Vorfahren-Frames. Eine Interaktion im Elternfenster aktiviert ein ursprungsfremdes Kind-iframe nicht.
Kompatibilität: In Chrome/Edge ab Version 72, in Safari ab 16.4 und in Firefox erst ab 120 verfügbar. Für ältere Browser mit navigator.userActivation?.hasBeenActive absichern und einen Ersatzweg vorsehen.
Nicht in Web-Workern verfügbar.

Siehe auch

UserActivation UserActivation.isActive Navigator.userActivation HTMLMediaElement.play() Window.open() WorkerLocation.hash