Firebase Cloud Messaging (FCM) API v1
Cloud Service Integration by Google LLC
Description
Firebase Cloud Messaging delivers push notifications to iOS and Android devices for time-sensitive events including certification expiry warnings, expense claim approval updates, coordinator escalation alerts, assignment reminders, and scenario-based motivational nudges. FCM tokens are managed per device and refreshed automatically, with the server-side dispatch executed from Supabase Edge Functions to protect FCM server key confidentiality.
Detailed Analysis
Firebase Cloud Messaging (FCM) delivers the push notification capability that keeps peer mentors and coordinators informed of time-sensitive events without requiring them to open the app. This includes certification expiry warnings that protect HLF from having uncertified mentors operating, expense claim approval updates that reduce administrative friction, and escalation alerts that ensure coordinators can respond promptly to at-risk mentoring relationships. FCM is provided by Google at no per-message cost under the Firebase free tier, making this a high-value capability with negligible direct cost. The integration is architecturally isolated: all dispatch is executed server-side via Supabase Edge Functions, ensuring the FCM server key is never exposed in the mobile binary.
An in-app notification centre provides a resilient fallback so no critical notification is ever silently lost, and email fallback is available for certification expiry alerts when push delivery is unavailable. This combination of zero marginal cost, platform-native delivery, and multi-layer fallback makes FCM the appropriate and low-risk choice for the project's notification requirements.
FCM spans twelve components including token management, permission handling, notification dispatch, and five domain-specific notification services covering approvals, declarations, certifications, pauses, and reminders. This breadth means notification delivery touches nearly every user-facing workflow and must be tested across both iOS and Android. Key setup dependencies include Firebase project creation, Google service account key provisioning for the server-side Edge Function, APNs key configuration in the Firebase console for iOS, and inclusion of google-services.json and GoogleService-Info.plist in the app build. iOS push delivery additionally requires APNs configuration, which involves Apple Developer account access.
Testing must cover permission grant flows, foreground and background notification delivery, token refresh scenarios, and fallback to the in-app notification centre when push is unavailable. The integration carries no licensing cost risk, but the diversity of notification types and the twelve dependent components mean integration testing is substantial. Ongoing maintenance is low once configured — FCM token rotation is automatic, and Firebase console provides delivery reports without custom instrumentation.
FCM HTTP v1 API is used for all push dispatch, authenticated via a Google service account JSON key scoped to https://www.googleapis.com/auth/firebase.messaging. The server key is stored exclusively in the Supabase Edge Function environment variable FCM_SERVICE_ACCOUNT_KEY and is never bundled in the mobile binary. Client-side, the firebase_messaging Flutter package (>=14.0.0) manages device token registration, refresh, and permission prompting. FCM tokens are synced to the database on registration and refresh.
Dispatch is triggered by domain events across multiple services — ApprovalsNotificationService, CertificationReminderService, DeclarationNotificationService, PauseNotificationService, and others — all routing through the FCMPushNotificationSender and FCMNotificationDispatcher. On InvalidRegistration errors, stale tokens are automatically purged. Notification payloads are intentionally minimal — full content is fetched from the API on open to avoid stale data in notifications. The in-app notification centre (backed by the PushNotificationDispatcher) persists all notifications independently of push delivery success, ensuring resilience when devices are offline or permissions are denied.
FCM HTTP v1 supports 600,000 messages per minute, far exceeding this project's scale.
Using Components (12)
Dependencies (4)
Authentication
| Type | Oauth |
| Requirements | Firebase project with FCM enabled, Google service account JSON key for FCM HTTP v1 API, google-services.json (Android) and GoogleService-Info.plist (iOS) in app |
| Scopes | https://www.googleapis.com/auth/firebase.messaging |
Configuration
FCM_SERVICE_ACCOUNT_KEY (server-side Edge Function only)
Error Handling
Monitoring
Performance
| Latency | < 5s for push delivery to online device |
| Availability | Degraded gracefully via in-app notification centre when push unavailable |
Cost Implications
| Pricing Model | Free — Firebase Cloud Messaging has no per-message cost |