IdleDetector.start() — Methode · JavaScript-Referenz

Signatur

IdleDetector.prototype.start(options)

Beschreibung

Mit start() aktiviert ein IdleDetector-Objekt die Überwachung. Ab dann löst der Detektor das Ereignis change aus, sobald sich userState ("active"/"idle") oder screenState ("locked"/"unlocked") ändert. Als „idle“ gilt der Benutzer, wenn er für mindestens die angegebene Schwelle (threshold) keine Eingaben am Gerät macht, also auch nicht in anderen Programmen, oder wenn der Bildschirm gesperrt ist.

Vor dem Aufruf braucht die Seite die Berechtigung "idle-detection". Die fordert man mit IdleDetector.requestPermission() an, und dieser Aufruf muss aus einer Benutzeraktion kommen, etwa einem Klick. Fehlt die Berechtigung, wird das Promise von start() mit einem NotAllowedError abgelehnt.

Typische Einsatzfälle sind Chat- und Kollaborationsanwendungen, die „abwesend“ anzeigen, Kiosk-Anwendungen, die nach Inaktivität auf den Startbildschirm zurückkehren, und Anwendungen, die teure Benachrichtigungen oder Synchronisation pausieren, solange niemand vor dem Gerät sitzt. Die Überwachung beenden Sie, indem Sie ein AbortSignal übergeben und später abort() aufrufen.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Konfigurationsobjekt mit den folgenden Eigenschaften.
$options.threshold	number	implementierungsabhängig	Wie lange der Benutzer mindestens inaktiv sein muss, bevor er als `"idle"` gilt, in Millisekunden. Der Wert muss mindestens 60000 (1 Minute) sein, sonst wird ein `TypeError` geworfen.
$options.signal	AbortSignal		Signal eines `AbortController`, mit dem die Überwachung beendet wird. Ist das Signal schon abgebrochen, wird das Promise sofort mit einem `AbortError` abgelehnt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das sich mit undefined erfüllt, sobald die Überwachung läuft. Es wird abgelehnt mit NotAllowedError (Berechtigung fehlt), TypeError (threshold kleiner als 60000), AbortError (Signal abgebrochen) oder InvalidStateError (Detektor läuft schon).

Beispiele

Berechtigung anfordern und Überwachung starten

// Muss aus einer Benutzeraktion heraus aufgerufen werden
const button = document.querySelector('#idle-start');

button.addEventListener('click', async () => {
  if (!('IdleDetector' in window)) {
    console.log('Idle Detection API wird nicht unterstützt.');
    return;
  }

  const state = await IdleDetector.requestPermission();
  if (state !== 'granted') {
    console.log('Berechtigung verweigert.');
    return;
  }

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

  await detector.start({ threshold: 60_000 });
  console.log('Überwachung gestartet.');
});

Überwachung gestartet. Benutzer: idle, Bildschirm: unlocked

Überwachung mit AbortController beenden

const controller = new AbortController();
const detector = new IdleDetector();

detector.onchange = () => {
  console.log('Status:', detector.userState);
};

try {
  await detector.start({
    threshold: 5 * 60_000, // 5 Minuten
    signal: controller.signal,
  });
  console.log('Läuft.');
} catch (err) {
  console.error(err.name, err.message);
}

// Später, z. B. beim Abmelden:
document.querySelector('#logout').addEventListener('click', () => {
  controller.abort();
  console.log('Überwachung beendet.');
});

Läuft. Überwachung beendet.

Chat-Status automatisch auf „abwesend“ setzen

const setPresence = async (status) => {
  await fetch('/api/presence', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ status }),
  });
};

const startPresenceTracking = async () => {
  const detector = new IdleDetector();

  detector.addEventListener('change', () => {
    const away = detector.userState === 'idle' || detector.screenState === 'locked';
    setPresence(away ? 'away' : 'online');
  });

  try {
    await detector.start({ threshold: 10 * 60_000 });
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      console.warn('Keine Berechtigung für idle-detection.');
    } else {
      throw err;
    }
  }
};

startPresenceTracking();

Fehler bei zu kleinem Schwellwert

const detector = new IdleDetector();

try {
  await detector.start({ threshold: 30_000 });
} catch (err) {
  console.log(err.name);
}

TypeError

// Wichtig · Fallstricke

Browserunterstützung: Die API ist experimentell und gibt es nur in Chromium-Browsern (Chrome, Edge, Opera ab Version 94). Firefox und Safari lehnen sie aus Datenschutzgründen ab. Prüfen Sie deshalb immer vorher mit 'IdleDetector' in window, ob sie verfügbar ist.
Nur in sicheren Kontexten: Die API steht nur über HTTPS bzw. auf localhost zur Verfügung. In iframes muss die Permissions Policy idle-detection sie erlauben.
Mindestschwelle: threshold muss mindestens 60000 ms betragen. Kleinere Werte führen zu einem TypeError. Diese Untergrenze soll verhindern, dass sich das Eingabeverhalten des Benutzers genau nachverfolgen lässt.
Berechtigung: IdleDetector.requestPermission() braucht eine Benutzeraktion (transient activation). Ohne erteilte Berechtigung schlägt start() mit NotAllowedError fehl.
Kein Neustart nach Abbruch: Ein erneuter start()-Aufruf auf einem laufenden Detektor führt zu InvalidStateError. Um nach abort() neu zu starten, legen Sie am besten einen neuen IdleDetector und einen neuen AbortController an.
Datenschutz: Die API verrät, ob jemand am Gerät arbeitet, auch außerhalb Ihrer Seite. Nutzen Sie sie nur, wenn es einen klaren Zweck gibt, und erklären Sie diesen dem Benutzer.

Siehe auch

BarcodeDetector.detect() IdleDetector.requestPermission() Sensor.start() MediaRecorder.start() MessagePort.start()