Firebase Cloud Messaging (FCM)
Send push notifications to your Android, iOS, and web app users through Firebase Cloud Messaging. Zeotap calls the FCM HTTP v1 API on your behalf, delivering a notification to each device token in an audience (batch) or when a user reaches a journey step (real-time).
Prerequisites
- A Firebase project with the Firebase Cloud Messaging API enabled (Google Cloud Console → APIs & Services → Library).
- A Google Cloud service account with the Firebase Cloud Messaging API Admin role, and a JSON key downloaded for it.
- Your users’ FCM registration tokens available as a column in your data warehouse (your app must be instrumented with the Firebase SDK to generate them, and must send updated tokens to Zeotap when they change).
Authentication
FCM uses a Google service account JSON key. Zeotap exchanges it for a short-lived OAuth 2.0 access token (scope firebase.messaging), caches the token, and refreshes it automatically.
- In Google Cloud Console, go to IAM & Admin → Service Accounts and create a service account.
- Assign it the Firebase Cloud Messaging API Admin role.
- Open the service account → Keys → Add Key → Create New Key → JSON and download the file.
- In Zeotap, upload or paste the JSON into the Service Account JSON field when configuring the destination.
Configuration
| Field | Type | Required | Description |
|---|---|---|---|
| Service Account JSON | File | Yes | The service account JSON key for your Firebase project |
| Firebase Project ID | Text | No | The Firebase Project ID. Defaults to the project_id inside the service account JSON |
Target Settings
| Field | Type | Required | Description |
|---|---|---|---|
| Android Priority | Select | No | high (wakes the device immediately) or normal (may be delayed to save battery). Default high |
| Time To Live (seconds) | Number | No | How long FCM stores the message if the device is offline. Blank uses the FCM default (4 weeks) |
| Analytics Label | Text | No | Label recorded against every send for campaign attribution in Firebase Analytics |
| Dry Run (validate only) | Toggle | No | Validate each message without delivering it. Use to test payloads and credentials |
Supported Operations
Sync Modes
| Mode | Supported |
|---|---|
| Insert | Yes |
| Upsert | — |
| Update | — |
| Mirror | — |
Each sync sends a notification to every delivered device token. A push cannot be un-sent, so there is no update, upsert, or mirror semantics — members removed from an audience simply stop receiving notifications.
Audience Sync Modes
| Mode | Supported |
|---|---|
| Add | Yes |
| Remove | — |
| Mirror | — |
Use Add to notify members as they enter a segment (delta sends on recurring syncs).
Features
- Field Mapping: Yes
- Schema Introspection: No
Required Mapping Fields
| Field | Description |
|---|---|
| Device Token | The FCM registration token for the target device. One notification is sent per token. |
Default Destination Fields
| Field | Type | Description |
|---|---|---|
token | string | FCM registration token for the target device (required) |
title | string | Bold heading shown in the notification |
body | string | Main descriptive text of the notification |
image | string | URL of an image shown in the expanded notification (Android and iOS 15+) |
data | json | Custom key-value pairs delivered silently to the app. All values are sent as strings; combined payload max 4 KB |
Map title/body/data from personalized columns in your model for per-user content, or leave them constant for a broadcast-style campaign.
How It Works
The FCM HTTP v1 API accepts one device token per request — there is no multicast. For a batch audience, Zeotap fans out the sends with controlled concurrency, respecting the FCM project quota. Transient errors (rate limiting or temporary unavailability) are retried automatically with exponential backoff. Device tokens that FCM reports as permanently invalid (for example, the app was uninstalled) are recorded in the sync run’s error report so they can be reviewed.
For real-time use, add a Send to destination step targeting this destination inside a journey — each member is notified when they reach that step.
Rate Limits
| Limit | Value |
|---|---|
| Default send quota | 600,000 messages per minute, per Firebase project |
| Over-quota response | Retried automatically with backoff |
| Payload size | 4 KB maximum (notification + data) |
| Device token expiry | Tokens inactive for 270 days are invalidated by FCM |
Troubleshooting
Authentication failed / permission denied
Confirm the service account has the Firebase Cloud Messaging API Admin role and that the Firebase Cloud Messaging API is enabled for the project. Re-upload the JSON key if it was rotated. Use the Test Connection button to validate the credentials.
Notifications are not delivered but the sync succeeds
Enable Dry Run to validate payloads, then disable it for real sends. A successful send only means FCM accepted the message — delivery also depends on the device being reachable and the token being valid.
A device token shows as invalid or unregistered
This means the app was uninstalled, the token was rotated, or it expired after inactivity. These tokens appear in the sync run’s error report. Ensure your app sends refreshed tokens to Zeotap so profiles stay current.
Messages are delayed on Android
Set Android Priority to high for time-sensitive notifications so the device is woken immediately instead of batching delivery to save battery.
Payload too large
The combined notification + data payload must be under 4 KB. Reduce the size of your mapped data values or move large content behind a deep link.
Rate limit (quota) errors
Sends are retried automatically with backoff. If you consistently approach the 600,000 messages/minute project quota, request a quota increase from Firebase Support or split the audience across smaller, staggered syncs.