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	✅	✅ + `screenOn`
iOS	✅	✅ (data-protection APIs)
Web · macOS · Windows · Linux	✅	—

On web and desktop, foreground/background reflect window focus/blur (a focused window is online, a blurred or minimized one is offline) — there is no device-lock concept there.

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

When you pass idleTimeout, feed user interaction so the timer can reset — either 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.