flutter_lockscreen_alert #

A Flutter plugin to show critical alert UI on the device lock screen using Android full-screen intents. Use it for incoming calls, bookings, or any time-sensitive alert that must be visible and interactive when the screen is locked.

Features #

• Lock-screen UI: Your Flutter widget is shown over the lock screen when the device is locked.
• Generic API: Pass any Map<String, dynamic> payload (e.g. booking id, from/to, fare) and build your own UI in Dart.
• Full-screen intent: Uses Android’s recommended path for critical alerts (notification with fullScreenIntent).
• Stream of actions: Listen to LockscreenAlert.onAction for dismissed / accepted from your lock-screen UI.

Setup #

1. Dependencies #

dependencies:
  flutter_lockscreen_alert: ^1.0.0

2. Android #

• Min SDK: 21
• Permissions: The plugin declares USE_FULL_SCREEN_INTENT and POST_NOTIFICATIONS (API 33+). On Android 13+, ensure your app requests notification permission if needed.
• Full-screen intent: On some devices the user must allow “full screen notifications” for your app (e.g. in Settings → Apps → Your app → Notifications).

3. Register the lock-screen entrypoint #

Your app must provide a top-level entrypoint that Flutter will run when the lock-screen UI is shown. In your main.dart (or a file imported by it), add:

import 'package:flutter_lockscreen_alert/flutter_lockscreen_alert.dart';

@pragma('vm:entry-point')
void lockscreenAlertMain() async {
  WidgetsFlutterBinding.ensureInitialized();
  // Optional: init your app (e.g. theme, localization)
  runApp(MyLockscreenAlertApp());
}

class MyLockscreenAlertApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: LockscreenAlertScreen(),
    );
  }
}

class LockscreenAlertScreen extends StatefulWidget {
  @override
  State<LockscreenAlertScreen> createState() => _LockscreenAlertScreenState();
}

class _LockscreenAlertScreenState extends State<LockscreenAlertScreen> {
  Map<String, dynamic>? _payload;

  @override
  void initState() {
    super.initState();
    _loadPayload();
  }

  Future<void> _loadPayload() async {
    final payload = await LockscreenAlert.getPayload();
    if (mounted) setState(() => _payload = payload);
  }

  @override
  Widget build(BuildContext context) {
    if (_payload == null) return const Scaffold(body: Center(child: CircularProgressIndicator()));
    return Scaffold(
      body: SafeArea(
        child: Column(
          children: [
            Text('Alert: ${_payload!['title']}'),
            ElevatedButton(
              onPressed: () async {
                await LockscreenAlert.notifyAccepted();
              },
              child: Text('Accept'),
            ),
            TextButton(
              onPressed: () async {
                await LockscreenAlert.notifyDismissed();
              },
              child: Text('Dismiss'),
            ),
          ],
        ),
      ),
    );
  }
}

You can replace LockscreenAlertScreen with your own widget (e.g. your booking card).

Usage #

Show an alert on the lock screen #

final id = await LockscreenAlert.show(
  payload: {
    'id': 'booking_123',
    'from': 'Airport',
    'to': 'Downtown',
    'fare': '\$25',
  },
  notificationTitle: 'New booking',
  notificationBody: 'Tap to view',
);

Listen for user actions #

LockscreenAlert.onAction.listen((event) {
  if (event.action == 'accepted') {
    // Open app and navigate to booking, e.g. event.data
  } else if (event.action == 'dismissed') {
    // User closed the alert
  }
});

Dismiss programmatically #

await LockscreenAlert.dismiss(id: id);

Check support #

final supported = await LockscreenAlert.isSupported();

Custom entrypoint name #

If you prefer a different entrypoint than lockscreenAlertMain, set it before calling show:

LockscreenAlert.entrypoint = 'myCustomEntrypoint';

and register that name in your Dart entrypoint (e.g. in main.dart):

@pragma('vm:entry-point')
void myCustomEntrypoint() { ... }

You must also pass this name from the host app to the plugin (the plugin’s default is lockscreenAlertMain). The Android side currently uses the constant lockscreenAlertMain; to use a custom name you’d need to pass it via a plugin method (e.g. setEntrypoint) and have the native side use it when starting the engine. For 1.0 we keep the single default entrypoint.

iOS #

This plugin does not implement iOS. For a similar experience on iOS you would use CallKit (and optionally PushKit). We may add an iOS implementation in a future release.

Publishing to pub.dev #

1. From the package directory run dart pub publish --dry-run, then fix any issues.
2. Run dart pub publish when ready.

License #

Apache License 2.0. See LICENSE.