Skip to content

Migrating to the Firebase Cloud Messaging API

Learn how to migrate from Google’s deprecated Cloud Messaging API to their fully-supported Firebase Cloud Messaging (FCM) API. For more information, see Google’s Firebase FAQ - 2023.

Rate limit

Firebase Cloud Messaging (FCM) API has a default rate limit of 600,000 requests per minute. If you reach this limit, Braze will automatically try again in a few minutes. To request an increase, contact Firebase Support.

Migrating to FCM

Step 1: Verify your Project ID

First, open Google Cloud. On your project’s home page, check the number in the Project ID field—you’ll compare this to the one in your Firebase project next.

The Google Cloud project's home page with the "Project ID" highlighted.

Next, open Firebase Console, then select  Settings > Project settings.

The Firebase project with the "Settings" menu open.

In the General tab, verify the Project ID matches the one listed in your Google Cloud project.

The Firebase project's "Settings" page with the "Project ID" highlighted.

Step 2: Verify your Sender ID

First, open Braze, then select  Settings > App Settings.

The "Settings" menu open in Braze with "App Settings" highlighted.

Under your Android app’s Push Notification Settings, check the number in the Firebase Cloud Messaging Sender ID field—you’ll compare this to the one in your Firebase project next.

The form for "Push Notification Settings".

Next, open Firebase Console, then select  Settings > Project settings.

The Firebase project with the "Settings" menu open.

Select Cloud Messaging. Under Cloud Messaging API (Legacy), verify the Sender ID matches the one listed in your Braze dashboard.

The Firebase project's "Cloud Messaging" page with the "Sender ID" highlighted.

Step 3: Enable the Firebase Cloud Messaging API

In Google Cloud, select the project your Android app is using, then enable the Firebase Cloud Messaging API.

Enabled Firebase Cloud Messaging API

Step 4: Create a Service Account

Next, create a new service account, so Braze can make authorized API calls when registering FCM tokens. In Google Cloud, go to Service Accounts, then choose your project. On the Service Accounts page, select Create Service Account.

A project's service account home page with "Create Service Account" highlighted.

Enter a service account name, ID, and description, then select Create and continue.

The form for "Service account details."

In the Role field, find and select Firebase Cloud Messaging API Admin from the list of roles. For more restrictive access, create a custom role with the cloudmessaging.messages.create permission, then choose it from the list instead. When you’re finished, select Done.

The form for "Grant this service account access to project" with "Firebase Cloud Messaging API Admin" selected as the role.

Step 5: Verify permissions (optional)

To verify which permissions your service account has, open Google Cloud, then go to your project and select IAM. Under View By Principals, select Excess Permissions.

The "View By Principles" tab with the number of excess permissions listed for each principal.

Now you can review the current permissions assigned to your selected role.

The list of current permissions assigned to the selected role.

Step 6: Generate JSON credentials

Next, generate JSON credentials for your FCM service account. On Google Cloud IAM & Admin, go to Service Accounts, then choose your project. Locate the FCM service account you created earlier, then select  Actions > Manage Keys.

The project's service account homepage with the "Actions" menu open.

Select Add Key > Create new key.

The selected service account with the "Add Key" menu open.

Choose JSON, then select Create. If you created your service account using a different Google Cloud project ID than your FCM project ID, you’ll need to manually update the value assigned to the project_id in your JSON file.

Be sure to remember where you downloaded the key—you’ll need it in the next step.

The form for creating a private key with "JSON" selected.

Step 7: Upload your JSON credentials to Braze

In Braze, select  Settings > App Settings.

The "Settings" menu open in Braze with "App Settings" highlighted.

Under Push Notification Settings, select Upload JSON File, then choose the file you generated earlier. When you’re finished, select Save.

The form for "Push Notification Settings" with the private key updated in the "Firebase Cloud Messaging Server Key" field.

Step 8: Test your new credentials (optional)

As soon as you upload your credentials to Braze, you can start sending push notifications using your new credentials. To test your new credentials, send a real or test push notification to your app using FCM or Braze. If the push notification goes through, everything is working. If it doesn’t:

If you’re still having trouble, see Reverting your credentials.

Reverting your credentials

You can delete your new credentials and restore your legacy credentials at any time. As soon as your credentials are restored, you can start sending push notifications using your legacy credentials instead.

In Braze, select  Settings > App Settings. Under Push Notification Settings, select Revert Credentials.

The form for "Push Notification Settings" with the "Revert Credentials" button highlighted.

Frequently Asked Questions (FAQ)

How do I know my new credentials are working?

Your new credentials start working as soon as you upload them to Braze. To test them, select Test Credentials. If you get an error, you can always revert your credentials.

Do I need to migrate to FCM for my unused apps or development apps?

No. However, your unused apps and development apps will continue to show a warning message asking you to migrate. To remove this message, you can either upload new credentials, or delete these apps from your workspace. If you choose to delete these apps, be sure to check with your team first in case someone is using them.

Where can I check error messages?

You can review push notification errors in your message activity log.

Before migrating, do I need to update my app or SDK?

No. You only need to upload your new credentials to Braze.

Do I need to delete my old legacy credentials first?

No. If you ever need to delete your new credentials, your legacy credentials can be used instead.

After migrating, why is there still a warning message in Braze?

You’ll continue to see this warning message if there’s at least one Android app in your workspace you still need migrate. Be sure to migrate all of your Android apps over to Google’s fully-supported FCM API.

After migrating, how long until I send push notifications again?

After migrating, you can start sending push notifications using your new credentials right away.

What if I created my service account using a different project than my FCM project?

If you created your service account using a different Google Cloud project ID than your FCM project ID, you’ll need to manually update the value assigned to the project_id in your JSON file after you create a new one.

HOW HELPFUL WAS THIS PAGE?
New Stuff!