unlock_detector 1.2.0

A Flutter plugin to detect device lock/unlock and app foreground/background events for user online/offline presence.

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

Status	Meaning	User
foreground	App is active and visible	online
idle	App open but user inactive	away
background	User switched away	offline
locked	Device screen locked	offline
unlocked	Device just unlocked	transitional
screenOn	Screen turned on (Android)	transitional

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

Platform support

Platform	foreground / background	idle	lock / unlock
Android	✅	✅ in-app	✅ + screenOn
iOS	✅	✅ in-app	✅ (data-protection APIs)
macOS · Windows · Linux	✅ window focus	✅ OS system-wide	—
Web	✅ window focus	✅ in-app	—

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.