Skip to main content

Local notifications

Nexconn Chat UI includes a lightweight local notification helper built on flutter_local_notifications. It is best-effort client-side behavior and is not the same as remote push delivery.

Local notifications can be shown only when the app process is alive and the platform allows notification delivery. If the app has been terminated by the system, remote push infrastructure is required to alert the user.

Enable local notifications​

Dart
final engineProvider = context.read<EngineProvider>();

await engineProvider.setupLocalNotification(enable: true);

Disable the helper at runtime:

Dart
await engineProvider.setupLocalNotification(enable: false);

The current switch value is exposed as EngineProvider.enableLocalNotification.

What the helper does​

When enabled, EngineProvider.notifyMessageReceived calls showLocalNotification(message). The helper:

  • Initializes FlutterLocalNotificationsPlugin.
  • Requests notification permission on Android, iOS, and macOS where the plugin supports it.
  • Uses a default Android channel with ID nexconn_chat_messages.
  • Uses the message sender user ID as the default title.
  • Uses messageSummary(message) as the default body.
  • Does not surface delivery failures through the helper API because local notification behavior depends on your app and platform setup.

For production integrations, add logging around your call to setupLocalNotification or showLocalNotification, record the platform permission state, and provide an in-app fallback such as a banner, badge refresh, or unread-count update when local notification delivery is not available.

You can show a local notification manually with custom text:

Dart
await engineProvider.showLocalNotification(
  message,
  title: 'New message',
  body: 'Open the app to view the latest message.',
);

Android notes​

For Android 13 and later, your app needs the runtime notification permission. Add the manifest permission in your app:

xml
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
<uses-permission android:name="android.permission.VIBRATE" />

The helper calls requestNotificationsPermission() through flutter_local_notifications, but your app should still decide the right timing and user education for permission prompts.

iOS and macOS notes​

The helper requests alert, badge, and sound permission through DarwinInitializationSettings and platform-specific permission APIs. If your app needs custom categories, actions, foreground presentation behavior, or notification service extensions, configure those in the app layer.

Remote push is separate​

Local notifications do not register a device token, do not wake a terminated app, and do not replace a remote push provider. Treat them as a convenience for foreground or background-running app sessions.

For production offline alerts, configure remote push delivery in your app and backend, then use local notifications only as an additional in-process presentation path.

Last updated on