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.

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

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

Step 2: Verify your Sender ID

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

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.

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

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

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.

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.

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

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.

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.

Now you can review the current permissions assigned to your 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.

Select Add Key > Create new key.

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.

Step 7: Upload your JSON credentials to Braze

In Braze, select  Settings > App Settings.

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

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:

• Verify your sender ID
• Verify your permissions
• Review push notification errors in your message activity log

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.

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.