IdleDetector.userState — Eigenschaft · JavaScript-Referenz

Signatur

IdleDetector.userState

Beschreibung

Die Eigenschaft userState des IdleDetector-Interfaces gibt an, ob der Benutzer gerade aktiv ist. Der Wert ist "active", wenn in der beim Aufruf von start() festgelegten Schwelle (threshold) eine Eingabe erfolgte (Tastatur, Maus, Touch o. Ä.), und "idle", wenn die Schwelle ohne Interaktion verstrichen ist.

Solange start() nicht aufgerufen wurde oder die Überwachung noch nicht läuft, ist der Wert null. Änderungen werden über das change-Event signalisiert. Dort liest man userState zusammen mit screenState aus ("locked" oder "unlocked").

Typische Einsatzfälle sind Chat- und Kollaborationsanwendungen, die den Status „abwesend“ anzeigen, Kiosk-Anwendungen, die sich nach Inaktivität zurücksetzen, oder Dashboards, die ressourcenintensive Aktualisierungen pausieren, solange niemand vor dem Gerät sitzt.

Rückgabewert

Typ

"active" | "idle" | null

Beschreibung

"active", wenn der Benutzer innerhalb der Schwelle interagiert hat, "idle" nach Ablauf der Schwelle ohne Interaktion, null, solange die Überwachung nicht läuft.

Beispiele

Status bei jeder Änderung protokollieren

const startIdleDetection = async () => {
  if (!('IdleDetector' in window)) {
    console.log('Idle Detection API nicht verfügbar');
    return;
  }
  // Berechtigung muss durch eine Benutzeraktion angefragt werden
  const permission = await IdleDetector.requestPermission();
  if (permission !== 'granted') {
    console.log('Berechtigung verweigert');
    return;
  }

  const detector = new IdleDetector();
  console.log('Vor start():', detector.userState);

  detector.addEventListener('change', () => {
    console.log(`Benutzer: ${detector.userState}, Bildschirm: ${detector.screenState}`);
  });

  await detector.start({ threshold: 60_000 }); // mindestens 60 Sekunden
};

document.querySelector('#start').addEventListener('click', startIdleDetection);

Vor start(): null Benutzer: active, Bildschirm: unlocked Benutzer: idle, Bildschirm: unlocked

Chat-Präsenzstatus „Abwesend“ setzen

const statusEl = document.querySelector('#presence');
const controller = new AbortController();

const watchPresence = async () => {
  if ((await IdleDetector.requestPermission()) !== 'granted') return;

  const detector = new IdleDetector();
  detector.addEventListener('change', () => {
    const away = detector.userState === 'idle' || detector.screenState === 'locked';
    statusEl.textContent = away ? 'Abwesend' : 'Online';
  });

  await detector.start({ threshold: 5 * 60_000, signal: controller.signal });
};

document.querySelector('#enable-presence').addEventListener('click', watchPresence);
// Überwachung später beenden:
// controller.abort();

Dashboard-Polling bei Inaktivität pausieren

let timer = null;
const refresh = () => console.log('Daten aktualisiert', new Date().toLocaleTimeString());

const setPolling = (active) => {
  clearInterval(timer);
  timer = active ? setInterval(refresh, 10_000) : null;
  console.log(active ? 'Polling läuft' : 'Polling pausiert');
};

document.querySelector('#start').addEventListener('click', async () => {
  if ((await IdleDetector.requestPermission()) !== 'granted') return;
  const detector = new IdleDetector();
  detector.addEventListener('change', () => setPolling(detector.userState === 'active'));
  await detector.start({ threshold: 120_000 });
  setPolling(detector.userState === 'active');
});

Polling läuft Polling pausiert

// Wichtig · Fallstricke

Kompatibilität: Nur in Chromium-Browsern (Chrome, Edge, Opera) ab Version 94 verfügbar. Firefox und Safari lehnen die API aus Datenschutzgründen ab. Vor der Nutzung immer per 'IdleDetector' in window prüfen.
Sicherer Kontext & Berechtigung: Die API funktioniert nur über HTTPS und erfordert die Berechtigung "idle-detection". IdleDetector.requestPermission() muss durch eine Benutzeraktion ausgelöst werden, etwa einen Klick. In iframes ist zusätzlich die Permissions Policy idle-detection nötig.
Wert null: Vor dem Auflösen von start() und nach einem Abbruch über das AbortSignal ist userState null. Den Code entsprechend absichern.
Mindestschwelle: threshold muss mindestens 60 000 ms betragen, sonst wirft start() einen TypeError.
Datenschutz: Aktivitätsdaten sind sensibel. Nur einsetzen, wenn der Nutzen klar ist, und den Benutzer darüber informieren.

Siehe auch

IdleDetector.screenState MediaRecorder.state VideoDecoder.state VideoEncoder.state AudioDecoder.state