Repository navigation
Flutter
This is a server-side Laravel package. It does not ship Flutter code or change the consuming mobile application. The host supplies authenticated API routes corresponding to service operations.
- Generate and persist a random UUID installation identifier for this app installation. It is not a user ID or authentication secret.
- Request the operating system's notification permission at an appropriate point in the application's flow.
- Obtain an Android FCM token or a direct native iOS APNs token.
- After application authentication, send installation ID, platform, provider token and optional device name to the host's authenticated device-registration endpoint.
- Store the returned package device UUID for owner-scoped updates/removal. Tokens should not be echoed in API responses.
- On token refresh, resubmit the same installation ID with the latest token. Also reconcile registration on authenticated startup to recover missed refresh callbacks.
- Unregister while the old authenticated session is still available during logout. A new account cannot silently claim an existing registration; use the host's explicit authorized account-switch flow.
OS permission and backend push enablement are separate. Permission denial may prevent display even if the provider accepts a submission. Recheck settings when the app resumes after the user changes OS permissions.
Use the required FCM Android client components only for transport. A Flutter app may integrate firebase_messaging for its Android build or use a native Android transport bridge. Configure the correct app/project identity and notification channel/permission handling. Do not enable Firebase Authentication, Firestore, Realtime Database, Analytics or hosted notification management for this package.
The server sends a visible notification plus provider-neutral custom data. Handle foreground messages in the app; background notification payloads may be displayed by the OS/FCM integration. Avoid displaying a second local notification for an alert the OS has already displayed. Background/terminated execution is subject to Android restrictions; force-stop and OEM power management can prevent delivery/execution.
See Google's Flutter receive guide and Android client setup.
Do not configure Firebase Messaging on iOS for this integration. Enable the Apple Push Notifications capability and appropriate provisioning entitlement. The iOS application obtains permission through UserNotifications and registers with APNs using UIApplication.registerForRemoteNotifications().
Receive the native token in application(_:didRegisterForRemoteNotificationsWithDeviceToken:), convert the bytes to the canonical hexadecimal token, and bridge it to Dart through the application's native integration (for example a Flutter platform channel). Register refreshed tokens with the authenticated backend. Handle registration failure without treating a cached token as proof of active delivery.
The Flutter application owns this native bridge; flutter_local_notifications does not obtain a remote APNs token or replace APNs registration. Use native UserNotifications delegate callbacks for foreground receipt/taps and bridge those into the Dart navigation flow. Match sandbox/production signing and backend configuration. Rich remote images require a notification service extension and image_url handling; the server sets mutable content but does not install that extension.
See Apple registration and Flutter platform channels.
Use flutter_local_notifications for local presentation where the host has elected to present a received foreground message locally. Initialize it during app startup; configure Android icons/channels and iOS permission/presentation behavior using the installed plugin version's documentation.
Handle its notification-response callback and launch details for local alerts. Remote APNs taps and FCM taps also need their transport/native callbacks; one local callback is not a complete remote-tap integration. Route all accepted taps through one application navigation function.
Custom push fields are notification_id, category, optional deep_link, optional image_url and JSON-encoded data. Validate deep links against an application allowlist; never execute arbitrary URLs or trust custom data as authorization. Use notification_id to deduplicate client processing and fetch current history/details over an authenticated API. Collapse/grouping is advisory provider behavior and does not replace idempotency or local deduplication.
For sensitive events, show a neutral body and fetch protected content only after authentication. Do not retain another account's notification details across logout.
The application's authenticated API should wrap NotificationHistoryService pagination, unread count, read/unread/delete operations, NotificationPreferenceService and owner-scoped device push settings. The package does not choose endpoint URLs or authentication. Show history independently of whether OS push was received, accepted, displayed or enabled.
Provider acceptance, client receipt, OS display and user interaction are different observations. A future acknowledgment feature would require authenticated, owner-scoped receipt reporting keyed by notification/device identity, replay protection and separately defined receipt semantics. This version has no acknowledgment endpoint, receipt table or receipt-only delivery states. Do not report a server acceptance timestamp as a client receipt.
