---
title: "Firebase Cloud Messaging"
description: "Use Firebase Cloud Messaging for MainSDK push notifications on Android and iOS - Firebase project, credentials, main.yaml, testing and swapping."
section: "integrations"
canonical: "https://mainsdk.dev/docs/integrations/firebase-cloud-messaging"
updated: "2026-10-28"
---

# Firebase Cloud Messaging

> Use Firebase Cloud Messaging for MainSDK push notifications on Android and iOS - Firebase project, credentials, main.yaml, testing and swapping.

Canonical: https://mainsdk.dev/docs/integrations/firebase-cloud-messaging · Updated: 2026-10-28

Firebase Cloud Messaging (FCM) is Google's push service. In a MainSDK app it is a push driver for [`notify`](https://mainsdk.dev/docs/interfaces/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.

## Interfaces it serves

### Notifications (`notify`)

- Status: Building for 0.3 · ships as a stable API
- Driver: `fcm` (Firebase Cloud Messaging)
- Docs: https://mainsdk.dev/docs/interfaces/notify.md

```yaml
notify:
  driver: fcm
```

Swap to another provider: `whatsapp-cloud`, `bird`, `msg91`, `twilio`, `local`, `apns`, `expo`, `resend`, `ses`, `onesignal`, `slack`, `pagerduty`, `opsgenie`, `webhook`.

## 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

```yaml title="main.yaml"
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 [TBD]; 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.

```ts title="app/notifications/setup.ts"
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](https://mainsdk.dev/docs/interfaces/notify).

## 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

```yaml title="main.yaml"
notify:
  push: { drivers: [fcm, apns], via: expo }   # was { drivers: [fcm, apns] }
```

> **Warning:** Push tokens are issued per service. Tokens registered for FCM directly are not Expo push tokens, so moving between direct FCM and Expo needs each device to register again. How MainSDK runs that move is [TBD].

## 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](https://mainsdk.dev/docs/interfaces/notify)
- [Apple Push Notification service](https://mainsdk.dev/docs/integrations/apns), [Expo](https://mainsdk.dev/docs/integrations/expo) and [OneSignal](https://mainsdk.dev/docs/integrations/onesignal)
- [Swap a driver](https://mainsdk.dev/docs/guides/swap-a-driver)