FCM Token Manager
Component Detail
Description
Registers and refreshes Firebase Cloud Messaging device tokens in Supabase, associating them with the authenticated user and device. Handles token rotation on FCM token refresh callbacks and removes stale tokens on logout. Used by the backend trigger service to resolve target devices for dispatch.
fcm-token-manager
Summaries
Push notifications are the primary channel for driving re-engagement in mobile applications. The FCM Token Manager ensures the platform always holds valid device identifiers to reach users reliably, maintaining the connection between the app and its users even as tokens rotate due to OS-level refresh cycles. Stale or missing tokens produce silent delivery failures — users miss time-sensitive notifications and the product loses a key engagement lever with no visible error. By automating token registration, rotation, and revocation, this component eliminates a common source of push notification delivery degradation, directly protecting engagement metrics and the user experience quality that institutional partners evaluate.
Medium-complexity component operating across mobile and backend contexts, requiring Firebase project setup and Supabase table provisioning as hard prerequisites before development starts. Token lifecycle management — registration on login, refresh on FCM callback, revocation on logout — spans multiple user flows and all three scenarios must be tested before release. The `onTokenRefresh` integration depends on FCM SDK behavior which varies between Android and iOS; budget time for platform-specific device testing. Backend dependency on `getTokensForUser(userId)` for push dispatch places this component on the critical path for notification delivery.
Ensure the Supabase device_tokens table has an index on userId to support performant lookups at scale.
Integrates the Firebase Cloud Messaging SDK via the `firebase_messaging` Flutter plugin alongside the Supabase client. On login, call `registerToken(userId, token)` with the FCM token from `FirebaseMessaging.instance.getToken()`. Wire `onTokenRefresh(callback)` to the `FirebaseMessaging.instance.onTokenRefresh` stream to transparently call `refreshToken(userId, newToken)`. `revokeToken(userId, token)` must be called in the logout flow and in the `onDeletedMessages` FCM callback for uninstall handling.
Supabase table schema should be `(id, user_id, token, device_id, platform, created_at, updated_at)` with a unique constraint on `(user_id, token)` to enable safe upserts and prevent duplicates. Backend trigger service consumes `getTokensForUser(userId)` to resolve FCM dispatch targets; apply RLS so users manage only their own rows while the service role bypasses RLS for reads.
Responsibilities
- Register device FCM token in Supabase on login and on token refresh
- Delete device token from Supabase on logout or app uninstall
- Provide current valid token for FCM dispatch lookups
Interfaces
registerToken(userId, token)
refreshToken(userId, newToken)
revokeToken(userId, token)
getTokensForUser(userId)
onTokenRefresh(callback)
Relationships
Dependents (2)
Components that depend on this component
Used Integrations (1)
External integrations and APIs this component relies on