UserActivation.isActive — Eigenschaft · JavaScript-Referenz

Signatur

navigator.userActivation.isActive

Beschreibung

Die Eigenschaft isActive der Schnittstelle UserActivation (erreichbar über navigator.userActivation) liefert true, wenn das Fenster gerade eine transiente Benutzeraktivierung hat. Diese entsteht durch eine echte Nutzerinteraktion wie keydown (außer Escape und einigen Sondertasten), mousedown, pointerdown (Maus), pointerup (nicht Maus) oder touchend. Nach einer browserabhängigen Zeitspanne läuft sie ab, typischerweise nach einigen Sekunden.

Viele leistungsstarke APIs setzen eine transiente Aktivierung voraus, zum Beispiel element.requestFullscreen(), window.open() für Pop-ups, navigator.clipboard.write(), navigator.share() oder das automatische Abspielen von Medien mit Ton. Manche dieser APIs verbrauchen die Aktivierung: Danach steht isActive wieder auf false, bis der Nutzer erneut interagiert.

Mit isActive lässt sich vor dem Aufruf einer solchen API prüfen, ob sie voraussichtlich gelingt. So kann man einen passenden Hinweis oder einen Fallback-Button anzeigen, statt eine abgelehnte Promise oder ein blockiertes Pop-up hinzunehmen. Die Schwester-Eigenschaft hasBeenActive gibt dagegen an, ob es jemals eine Aktivierung gab (die „klebrige“ Aktivierung).

Rückgabewert

Typ

boolean

Beschreibung

true, wenn gerade eine transiente Benutzeraktivierung besteht, sonst false.

Beispiele

Aktivierungsstatus direkt abfragen

// Ohne Nutzerinteraktion, z. B. direkt beim Laden der Seite
console.log(navigator.userActivation.isActive);

document.addEventListener('pointerdown', () => {
  // Innerhalb des Handlers gibt es eine frische Aktivierung
  console.log(navigator.userActivation.isActive);
});

false true // nach einem Klick

Vollbild nur anfordern, wenn es gelingen kann

const video = document.querySelector('video');

const goFullscreen = async () => {
  if (!navigator.userActivation?.isActive) {
    console.warn('Keine Benutzeraktivierung – bitte auf den Button klicken.');
    return;
  }
  try {
    await video.requestFullscreen();
  } catch (err) {
    console.error('Vollbild abgelehnt:', err.message);
  }
};

document.querySelector('#fullscreen-btn').addEventListener('click', goFullscreen);
// Ein Aufruf per Timer schlägt fehl, sobald die Aktivierung abgelaufen ist
setTimeout(goFullscreen, 10000);

Keine Benutzeraktivierung – bitte auf den Button klicken. // nach 10 s ohne Interaktion

Pop-up öffnen oder auf Fallback ausweichen

const openHelp = () => {
  const url = '/hilfe';
  if (navigator.userActivation?.isActive) {
    window.open(url, '_blank', 'noopener');
  } else {
    // Fallback: Link anzeigen, den der Nutzer selbst anklickt
    const link = document.createElement('a');
    link.href = url;
    link.target = '_blank';
    link.rel = 'noopener';
    link.textContent = 'Hilfe in neuem Tab öffnen';
    document.body.append(link);
  }
};

document.querySelector('#help').addEventListener('click', async () => {
  await fetch('/api/log-help-click'); // kann lange dauern
  openHelp(); // Aktivierung eventuell schon abgelaufen
});

// Wichtig · Fallstricke

Nicht mit hasBeenActive verwechseln: isActive ist nur kurz nach einer Interaktion true. hasBeenActive bleibt nach der ersten Interaktion dauerhaft true.
Verbrauch: APIs wie window.open() oder requestFullscreen() können die Aktivierung verbrauchen. Ein zweiter Aufruf direkt danach kann deshalb scheitern, obwohl isActive eben noch true war.
Ablaufzeit: Wie lange die Aktivierung gilt, ist browserabhängig (in Chromium etwa 5 Sekunden). Lange await-Ketten vor dem Aufruf einer geschützten API können sie ablaufen lassen.
Nicht fälschbar: Mit dispatchEvent() ausgelöste synthetische Events (isTrusted === false) erzeugen keine Aktivierung.
Ereignisse ohne Aktivierung: Die Escape-Taste, mousemove, scroll oder Hover-Ereignisse lösen keine Aktivierung aus.
Iframes: Eine Aktivierung wird an übergeordnete Frames weitergegeben, aber nicht an unabhängige Frames anderer Herkunft.
Kompatibilität: In Chromium schon lange verfügbar, in Firefox erst ab Version 120 und in Safari ab 16.4. Für ältere Browser mit navigator.userActivation?.isActive absichern.

Siehe auch

Window.open() PerformanceSoftNavigation.interactionId UserActivation.hasBeenActive Animation.startTime Presentation.receiver