Firebase Cloud Messaging

Firebase Cloud Messaging (FCM) is Google's push service. In a MainSDK app it is a push driver for notify: when push is the channel a person is reached on, FCM delivers to their Android device, and to iOS devices if you route Apple pushes through it. Pick FCM when you send push directly rather than through Expo, usually next to APNs.

notify:
  driver: fcm

Before you start

1. Create a Firebase project and add your Android app (and your iOS app, if FCM will deliver there too).
2. Create server credentials. Sending through FCM's HTTP v1 API uses a Google Cloud service account for the project. Give it only the permission to send messages.
3. For iOS through FCM: upload your APNs authentication key to the Firebase project, so FCM can hand iOS messages to Apple.
4. Use separate projects or credentials for stage and production.

Store the service account key in your secrets manager, never in code or the app bundle.

Configure

notify:
  channels: [push, whatsapp, sms, email]
  push: { drivers: [fcm, apns] }   # or via: expo

How the FCM driver takes its credentials is not in the spec yet; it will be a secret: reference such as secret:FCM_SERVICE_ACCOUNT (suggested name). A literal key fails validation with MAIN-CONFIG-0004.

Use it

Register the device for push in the app, then notify from the server as usual.

import { notify } from "mainsdk/notify";

await notify.push.register();   // asks permission, stores the token

await notify(user, { template: "order.shipped", category: "transactional" });

Local development and testing

• createTestApp() from @mainsdk/testing runs notify on its in-memory fake, which enforces opt-in, quiet hours and the no-personal-data rule.
• chaos.on("notify", { outage: true }) simulates a push outage.
• Until a push driver is configured, the push channel is skipped and the next channel is tried.

What MainSDK adds on top

• Push only with the person's opt-in, respecting opt-outs and quiet hours in their time zone.
• No personal data in push payloads; put an ID in data and load details in the app.
• A retry with the same idempotency key never sends twice.

See Notifications.

Limits and notes

• The FCM driver comes with the expo-adapter spec (phase 3, milestone 1.1).
• Web push for browsers is an open question in the email-notify spec.
• Where device tokens are stored is not in the spec yet.

Swap to or from it

notify:
  push: { drivers: [fcm, apns], via: expo }   # was { drivers: [fcm, apns] }

FAQ

Do I need FCM if I use Expo? Expo's push service delivers to Android through FCM, so you still need a Firebase project, but your app talks to Expo with via: expo.

Can FCM send to iOS? Yes, if you upload your APNs key to Firebase. Many apps send to Apple devices with the APNs driver directly instead.

Next

• Notifications
• Apple Push Notification service, Expo and OneSignal
• Swap a driver

Open questions