Notifications

Two notification layers

The Flutter template separates:

• Local notifications (helpers/notification.dart) — initialized for every profile and used to display local/foreground notifications.
• FCM/remote push (helpers/notification_push.dart, bootstrap/account_bootstrap.dart) — Account-only token retrieval, refresh listeners, background handling, and server sync.

The main bootstrap initializes local notifications after the first frame. It does not hold the native splash screen on network/FCM work.

Account push flow

For Account mode, initializeAccountPushNotifications():

1. Initializes Firebase and requests permission according to NotificationConfig.
2. Retrieves and listens for the FCM token.
3. Stores it securely and posts it to POST /api/v1/app/device-tokens when a Sanctum token exists.
4. Displays foreground FCM messages with flutter_local_notifications.
5. Registers a background FCM handler and logs notification-open events.

Configure Firebase options/files for the final Android package and iOS bundle ID. The Laravel admin panel reads storage/app/firebase-auth.json to send FCM messages and persists notification history.

Notification history

Authenticated Account users can load paginated history and use:

• GET /api/v1/app/notifications
• PUT /api/v1/app/notifications/{id}/read
• PUT /api/v1/app/notifications/read-all
• DELETE /api/v1/app/notifications/{id}
• DELETE /api/v1/app/notifications
• GET/PUT /api/v1/app/notifications/preferences

notification_history_provider.dart supports refresh, pagination, optimistic read/delete updates, and limited retry handling.

Guest behavior

Guest mode initializes local notification support but never initializes FCM, requests a device token, syncs notification preferences, or calls notification-history APIs. Notification settings stay in SharedPreferences.

The template does not expose a generic local scheduling helper. Add and test an explicit zonedSchedule/local scheduling path if the Guest app needs reminders; initialization alone is not scheduled-delivery support.

Native setup and testing

• Android: configure Firebase, notification channel/icon, and Android 13+ permission behavior.
• iOS: configure APNs credentials/capabilities through Firebase/EAS and test on a physical device.
• Test foreground, background, terminated, denied-permission, token-refresh, logout, and Guest flows.

Notification-open routing is currently logged/handled by the bootstrap/widget layer; add an allowlisted navigation contract before trusting arbitrary payload links.

Relevant files

• helpers/notification.dart
• helpers/notification_push.dart
• bootstrap/account_bootstrap.dart
• services/fcm_service.dart
• services/notification_history_service.dart
• providers/notification_history_provider.dart
• providers/notification_provider.dart