Web Push Notifications: Migrating to the FCM HTTP v1 API

If any of your Iterable projects use Firebase Cloud Messaging (FCM) to send mobile or web push notifications, migrate them to the FCM HTTP v1 API before July 22, 2024 (Google has changed the deadline from June 20 to July 22). On July 22, 2024, Google will start shutting down the legacy FCM API, and Iterable projects that still use it will no longer be able to send mobile or web push notifications.

# In this article

# Overview

Iterable can use Firebase Cloud Messaging (FCM) to send web push notifications. To do this, it relies on the FCM API. However, Google has deprecated the legacy FCM APIs, and replaced them with the FCM HTTP v1 API. Because of this, you must update any of your Iterable projects that use the legacy FCM APIs.

The instructions below describe how to:

1. Create a sandbox project in Iterable.
2. For each website to which you send web push notifications from Iterable:
   • Gather some preliminary information.
   • Create a JSON private key for the new FCM API.
   • Send a test push notification from your sandbox project.
   • Update your production Iterable projects.

If you have any questions, or if you need any help with the steps in this document, contact Iterable support.

# Step 1: Create a sandbox project in Iterable

In this step, you'll create a sandbox project. In subsequent steps, you'll add web push integrations to this project and use them to test your new FCM credentials.

To create a sandbox project:

1. Sign in to Iterable with a user that has the Create Projects org permission.

2. Create a new project.

   

   • For Name, provide a name that clearly identifies the project as a sandbox (non-production) project.

   • For Time zone, select any time zone that makes sense.

   • For Unique identifier, choose any unique identifier you like (email, userId, or hybrid). When sending test web push notifications, you'll target specific browser tokens, not user identifiers, so your selection here isn't particularly consequential in this case.

   • Click Create. Iterable creates the new project and switches you to it.

# Step 2: Test web push notifications in your sandbox project

For each website that you need to migrate to the new FCM API, the following steps describe how to:

1. Gather some preliminary information.
   • Find your legacy FCM server API key and sender ID.
   • Find a browser token for a test user.
2. Create JSON private keys for the new FCM API.
3. Use the new JSON private keys to send test messages from a sandbox project.
4. Update your production Iterable projects.

# Step 2.1: Find your website's legacy FCM server API key and sender ID

First, find the legacy server API key and sender ID you currently use to send web push notifications to the website under consideration.

If you have trouble upgrading your production Iterable projects to the new FCM API, you can use the FCM server API key to revert to the legacy FCM API — as long as Google hasn't shut it off yet (which will start happening on July 22, 2024).

To find your website's legacy FCM server API key and sender ID:

1. Sign in to Firebase: https://firebase.google.com

2. Click Go to console.

   

3. Click the tile that corresponds to the Firebase project you use for the website in question.

4. Click the settings gear and select Project settings.

   

5. Go to the Cloud Messaging tab.

6. In the Cloud Messaging API (Legacy) section, next to Server key, there's a Token value (some projects may have multiple tokens). A token is a legacy FCM server API key — copy one of them and keep it in a safe place, but don't share it with others.

   

7. In the Cloud Messaging API (Legacy) section, at the bottom of the table, there's a Sender ID. Copy this value and keep it in a safe place.

# Step 2.2: Find a browser token for a test user

Next, find the browser token for a test user — an internal user to whom you can send a test web push notification, to test your new FCM private key. This should be a user who has visited your website and agreed to receive web push notifications.

1. Find the userId or email associated with the Iterable user profile of an internal user who has has agreed to receive web push notifications from your website. This should not be an end user/customer, since you'll be sending a test push notification they'll actually receive.

2. Sign in to Iterable, with a user who has permission to View User Profiles and Data or Create and Manage User Profiles and Data.

3. Switch to the Iterable project that contains the test user's profile.

4. Navigate to Audience > User Lookup.

5. Enter the user's userId or email and click Search users.

6. On the user's profile, in the navigation menu, select User fields.

7. In the User fields section of the page, twirl open the browserTokens array. Copy a value:

   

# Step 2.3: Create a Firebase service account

Next, create a Firebase service account for the website you're testing, and give it sufficient permission to send web push notifications on your behalf (when you create a private key in the next step, you'll associate it with this Firebase service account):

1. Sign in to Firebase: https://firebase.google.com

2. Click Go to console.

3. Click the tile for the Firebase project you use for the website you're testing.

4. Click the settings gear and select Project settings.

5. Navigate to the Service accounts tab.

6. Click Manage service account permissions.

   

7. To create a new Firebase service account, click Create Service Account.

   

8. Under Service account details:

   

   • Enter a name, account ID, and description.

   • Then, click Create and Continue.

9. Under Grant this service account access to project:

   

   • Select a role: Firebase Cloud Messaging API Admin, or a custom role with permission cloudmessaging.messages.create.

   • Click Continue.

10. Under Grant users access to this service account:

    

    • Leave both fields blank.

    • Click Done.

11. You'll land back on the Service Accounts page.

# Step 2.4: Create and download a JSON private key for the new FCM API

Now, create and download a JSON private key associated with the Firebase service account you just created:

1. Make sure you're still in the Firebase console, in the correct project.

2. On the Service Accounts page, in the row for your new Firebase service account (created in the previous step), click the three dots in the Actions column. Then, choose Manage keys.

   

3. Select Add Key > Create new key, and choose JSON.

   

4. Click Create. This creates the JSON key and downloads it to your machine.

# Step 2.5: Configure your sandbox project to use your new FCM private keys

To configure your sandbox project to use the new JSON private keys for FCM:

1. Sign in to your sandbox Iterable project with a user who has the Setup and Manage Channels permission.

2. Navigate to Settings > Web Push.

3. In the HTTP V1 row of the Integrations table, click Configure.

   

4. In the Configure Firebase integration window, upload your JSON private key, and enter the Sender ID you found above.

   

5. Click Save.

# Step 2.6: Send a test message from your sandbox project

After you upload and save your JSON private keys for FCM, a Test Firebase integration window appears. From this window, send a test web push notification to verify that the new private keys work as expected.

In this window:

1. Paste the browser token you found in step 2.2, above. Remember, this should be a browser token for an internal user, not an end user or customer.
2. Enter a message title and message body.
3. If you like, enter the URL of an icon to associate with the web push notification and a URL to open when the user clicks the notification.
4. Click Send test. The test user should see the web push notification.

# Troubleshooting the test message from your sandbox project

If the test message doesn't arrive as expected, try the following:

• Make sure that the user to whom you're sending the test message has agreed to receive web push notifications from the website in question.
• Make sure you're using the correct browser token.
• Make sure the FCM private key file (JSON) you uploaded to Iterable is connected to a Firebase service account associated with the website you're testing.
• Make sure the Firebase service account associated with the FCM private key has permission cloudmessaging.messages.create.
• From the associated web push integration in a production Iterable project, try send a test web push notification to the same browser token you just tested from the sandbox project. If the test notification doesn't arrive on the user's device, your app may not be configured correctly to display push notifications.

If the test user still doesn't receive your test web push notification, contact Iterable support.

After you've tested your app in a sandbox environment, you can test update your

# Step 3: Update your production Iterable projects

After sending a successful test web push notification to a given website, update any production Iterable projects that are associated with that website.

For every relevant production Iterable project:

1. Sign in to the Iterable project, with a user who has permission to Setup and Manage Channels.

2. Navigate to Settings > Web Push.

3. In the Legacy Server Key row of the Integrations table, click Update.

   

4. In the Configure Firebase integration window:

   

   • Upload the JSON private keys you created for this website in step 2.4, above.

   • Enter the Sender ID you found in step 2.1, above.

   • Copy down the server key and sender ID shown in the window, in case you need to revert. These should match the values you found in step 2.1, above.

   • Click Save.

5. In the Test Firebase integration window:

   • Enter the same browser token you found in step 2.2, above.

   • Enter a message title and message body.

   • If you like, enter the URL of an icon to associate with the web push notification and a URL to open when the user clicks the notification.

   • Click Send test. The test user should receive the message.

# Troubleshooting a production project

If the test web push notification from your production project doesn't arrive as expected, you can re-upload your private key or revert to the legacy FCM API while you troubleshoot.

# Re-upload your private key

If you accidentally uploaded the wrong private key (JSON file), follow these steps to try again:

1. In Iterable, in the row associated with the web push integration you're updating, click the overflow menu (three dots). From this menu, select Edit integration.
2. In the Configure Firebase integration window, upload the correct private key (JSON file), enter the correct Sender ID, and click Save.
3. In the Test Firebase integration window, send a test push notification.

If the test message still doesn't appear on the test user's device, try reverting to your legacy API key while you troubleshoot the problem (see next section).

# Revert to your legacy FCM server key while you troubleshoot

To revert an Iterable project back to your legacy FCM server API key:

1. Sign in to your Iterable project.

2. Navigate to Settings > Web Push.

3. In the Integrations section, click the overflow button (three dots) and select Revert to legacy API key.

4. In the Configure Firebase integration window:

   • Enter your the FCM server key for the website in question.

   • Enter the FCM sender ID for the website in question.

   • Click Save.

5. In the Test Firebase integration window, send a test push notification.

# Troubleshooting ideas

To investigate why your production push integration isn't sending push notifications as expected:

• Make sure the FCM private key file (JSON) you uploaded to Iterable is connected to a Firebase service account associated with the website you're testing.
• Make sure the Firebase service account associated with the FCM private key has permission cloudmessaging.messages.create.