unlock_detector #

A Flutter plugin that detects foreground/background, idle, and device lock/unlock — ideal for user online/offline presence in chat apps and activity tracking.

Status types #

Helpers on each status: isOnline, isOffline, isIdle, isLocked, isUnlocked, isForeground, isBackground, isScreenOn.

Platform support #

On web and desktop, foreground/background reflect window focus/blur (a focused window is online, blurred or minimized is offline) — there is no device-lock concept there. On desktop, idle follows the OS system-wide idle time; on mobile and web it follows in-app interaction (see below).

Install #

dependencies:
  unlock_detector: ^1.1.0

iOS works with both CocoaPods and Swift Package Manager — no setup needed.

Usage #

import 'package:unlock_detector/unlock_detector.dart';

// Initialize once. Pass idleTimeout to enable idle detection.
await UnlockDetector.initialize(idleTimeout: const Duration(minutes: 5));

// Listen to status changes.
final sub = UnlockDetector.stream.listen((status) {
  if (status.isOnline) {
    // user is actively using the app
  } else if (status.isIdle) {
    // app open, user inactive
  } else if (status.isOffline) {
    // user left the app or locked the device
  }
});

// Read the latest status synchronously (null before the first event).
final now = UnlockDetector.currentStatus;

// One-shot lock check (Android reliable, iOS best-effort).
final locked = await UnlockDetector.isDeviceLocked();

// Clean up when done.
await sub.cancel();
await UnlockDetector.dispose();

Idle detection #

Pass idleTimeout to initialize() to get the idle status.

• Desktop (macOS/Windows/Linux): automatic — idle follows the OS system-wide idle time (any keyboard/mouse input). Nothing else to do.

• Mobile & web: feed in-app interaction so the timer can reset — call UnlockDetector.reportActivity() from your input handling, or wrap your app:

  runApp(UnlockDetector.activityDetector(child: const MyApp()));
  

Initialization failures throw UnlockDetectorException. Call UnlockDetector.getPlatformInfo() for a description of platform behavior.

Support #

If this plugin helps you, consider supporting development:

License #

MIT — see LICENSE.