Firebase Cloud Messaging

Firebase project setup for web, iOS, and Android push.

FCM delivers push notifications to web browsers, iOS, and Android. The backend sends messages via a Firebase service account — one token registry for all platforms.

Firebase project setup

Create a project in the Firebase Console
Register apps for each platform:
- Web — add a web app, copy the Firebase config object
- iOS — add iOS app with correct bundle ID
- Android — add Android app with correct package name
Download google-services.json (Android) and GoogleService-Info.plist (iOS) for mobile teams

Web — VAPID key

Required for browser push notifications:

Firebase Console → Project Settings → Cloud Messaging
Under Web configuration, generate a Web Push certificate (VAPID key pair)
Expose the public key to the frontend as NEXT_PUBLIC_FCM_VAPID_KEY

Browsers require HTTPS (except localhost) and a registered service worker before granting push permission.

Service account (backend)

Firebase Console → Project Settings → Service Accounts
Generate new private key → store JSON in AWS Secrets Manager
Map to env vars: FCM_PROJECT_ID, FCM_CLIENT_EMAIL, FCM_PRIVATE_KEY

Frontend environment (web)

dotenv

NEXT_PUBLIC_FIREBASE_API_KEY=...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your-project-id
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=...
NEXT_PUBLIC_FIREBASE_APP_ID=...
NEXT_PUBLIC_FCM_VAPID_KEY=BPxxx...

iOS — APNs configuration

Apple Developer → Certificates, Identifiers & Profiles → Keys
Create APNs Auth Key (.p8)
Upload to Firebase Console → Project Settings → Cloud Messaging → Apple app configuration

Android

No extra backend config — FCM handles delivery when google-services.json is in the app.

Device token lifecycle

Event	Action
User logs in	Client registers token via `POST /v1/devices` with `platform: web \| ios \| android`
Token refresh	Client re-registers (FCM may rotate tokens)
User logs out	Delete token from database
User denies web permission	Skip registration — fall back to Socket.io in-app only
`registration-token-not-registered`	Backend removes stale token on send failure

Platform support

Platform	Delivery when	Requires
Web	Tab backgrounded or closed	HTTPS, service worker, user permission
iOS	App backgrounded or closed	APNs key in Firebase
Android	App backgrounded or closed	`google-services.json` in app

Express implementation

See Push — FCM for firebase-admin setup, web client code, and send helpers.