Mobile 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 mobile 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 Iterable projects that use the legacy FCM APIs.

The instructions below describe how to:

1. Create a sandbox project in Iterable.
2. For each of your mobile apps:
   • 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

Before updating your mobile apps to use the new FCM HTTP v1 API, create a sandbox project in Iterable. You'll use this project to send test push notifications, to make sure everything is working right before upgrading your production mobile apps to the new FCM API.

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 push notifications, you'll target specific device 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 push notifications in your sandbox project

For each of the mobile apps to which you use Iterable to send push notifications through FCM, follow the steps below to:

1. Gather some preliminary information.
   • The app's legacy FCM server API key.
   • The app's package name and FCM message type.
   • A device 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 mobile app's legacy FCM server API key

First, find the legacy server API key and sender ID you currently use to send push notifications to the mobile app 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 mobile app's legacy FCM server API key:

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

2. Click Go to console.

   

3. Click the tile corresponding to the Firebase project you use for the mobile app 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.

   

# Step 2.2: Find your mobile app's package name and FCM message type

Next, find the package name and FCM message type associated with your app.

Every Android mobile app has a package name — a unique identifier such as com.example.pushtest. To find the package name associated with one of your Android apps, you can look at its definition in a production Iterable project:

1. With a user who has permission to View Channels or Setup and Manage Channels, sign in to a production Iterable project where the mobile app is defined.

2. Click Settings > Apps and Websites.

3. Click the tile that corresponds to your mobile app.

   

4. From the Details section, copy the app's Package Name. Save this value. You'll need it later when adding the app to a sandbox Iterable project (which you'll use to test your new FCM setup before updating your production Iterable projects).

   

5. While you're on this page, also note the app's Message Type (this is the Firebase message type, not the Iterable message type): Data notifications or Notification messages.

# Step 2.3: Find a device token for a test user

To test your new FCM private keys (JSON) in a sandbox Iterable project, you'll need the device token for a test user who has your app installed.

1. Find the userId or email associated with the Iterable user profile of an internal user who has your app installed. This should not be an end user/customer, since you'll be sending a test push notification they'll receive on device.

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 left navigation menu, select User fields.

7. In the User fields section of the page, open the devices array.

8. Look through each item in the devices array until you find one where appPackageName is your app's package name, and endpointEnabled is true.

   

9. Copy the object's token value. You'll use it later, to send a test push notification.

# Step 2.4: Create a Firebase service account

Next, create a Firebase service account and give it sufficient permission to send push notifications on your behalf. When you create a private key in the next step, you'll associate it with this Firebase service account. To create and configure a Firebase service account:

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

2. Click Go to console.

3. Click the tile corresponding to the mobile app you're working on.

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. Then, click Continue.

   

10. Under Grant users access to this service account, leave both fields blank and click Done.

    

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

# Step 2.5: 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.

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 app.

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.6: Add your mobile app to your Iterable sandbox project

To add a mobile app to your sandbox project:

1. Sign in to your sandbox Iterable project with a user who has the Setup and Manage Channels permission. (If necessary, create a new user with this permission.)

2. Navigate to Settings > Apps and Websites.

3. Click Add new.

4. Specify a Name, Platform (Android, most likely), and Package name (the package name you found in step 2.2, above).

   

5. Click Create app.

# Step 2.7: In the sandbox project, configure the mobile app's FCM push integration

Now, configure the mobile app in the sample project to use the new FCM private key. In your sandbox Iterable project, open the mobile app's definition. Then:

1. In the Push section, next to Firebase, click Configure. This brings up the Configure Firebase integration window.

   

2. For Firebase Cloud Messaging (FCM) type, choose Notification messages or Data notifications. Select the same value you found for this app in step 2.2, above.

3. Click Browse files. From your local machine, select the JSON private key you created for this app in step 2.2.2, above.

4. After your JSON private key uploads, click Save.

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

Now, test the sandbox push integration you just configured. After you upload your JSON private key and click Save, a Test Firebase integration window appears:

1. In this window, enter the device token you found in step 2.3, above. Remember: this token should be associated with an internal user of the app you're currently testing, not an end user or customer.

2. Enter a message and click Send test. Verify that the user receives the message on their device.

# Troubleshooting the test message from your sandbox project

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

• Make sure the device object from which you copied the token (remember, the token came from an object in a devices array on an Iterable user profile) has:
  • An appPackageName that matches your app's package name.
  • endpointEnabled set to true. If endpointEnabled is false, it means the push integration is inactive, and Iterable cannot send it any messages. Keep looking in the devices array until you find a device where endpointEnabled is true.
• Make sure the FCM private key file (JSON) you uploaded to Iterable is connected to a Firebase service account associated with the app you're testing.
• Make sure the Firebase service account associated with the FCM private key has permission cloudmessaging.messages.create.
• In your Iterable project, make sure you've correctly configured the push integration's FCM message type. If mobile app's original definition (in one of your production Iterable projects) has OS Notifications off, the sandbox project's push integration should use Data notifications. Otherwise, it should use Notification messages.
• From the mobile app definition in a production Iterable project, try sending a test push notification to the test user device token you found in step 2.3, above. 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 push notification, contact Iterable support.

# Step 3: Update your production Iterable projects

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

For every relevant production Iterable project:

1. Sign in to an Iterable project associated with the mobile app, with a user with the Setup and Manage Channels permission.

2. Navigate to Settings > Apps and Websites.

3. Click the tile associated with your mobile app. It should display an Update banner, indicating it must be updated to work with the new FCM API.

   

4. In the Push section, in the Firebase row, click Update.

   

5. In the Configure Firebase integration window:

   

   • The Firebase Cloud Messaging (FCM) type should match the value you found in step 2.2, above. DO NOT modify this setting.

   • Upload the new FCM private key (JSON) you created for this app in step 2.2.2, above.

   • Click Save.

6. In the Test Firebase integration window:

   

   • Enter the same device token you found in step 2.3, above.

   • Enter a message.

   • Click Send test and verify the message arrives on the user's device.

# Troubleshooting a production project

If your production test message doesn't arrive on the test user's device, take a look at the steps described in this section.

# Re-upload your private key

If you accidentally uploaded the wrong private key (JSON file), you can switch to the correct one:

1. On the far-right side of the row associated with the push integration you're updating, click the button identified by three dots. Then, select Edit integration.

   

2. Upload the correct private key (JSON file), and then click Save.

   

3. 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 your mobile app definition back to your legacy FCM server API key, make sure you're still in your production Iterable project, and that you're looking at the mobile app definition associated with the app you're updating. Then:

1. On the far-right side of the row associated with the push integration you need to revert, click the button identified by three dots and select Revert to legacy API key.

   

2. In the Configure Firebase integration window:

   

   • The Firebase Cloud Messaging (FCM) type should match the value you found in step 2.2, above. DO NOT modify this setting.

   • In the API Key field, paste the legacy server API key you found for this app in step 2.1, above.

   • Click Save.

3. In the Test Firebase integration window:

   • Enter the same device token you found in step 2.3, above.

   • Enter a message.

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

# Troubleshooting ideas

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

• Make sure the device object from which you copied the token (remember, the token came from an object in a devices array on an Iterable user profile) has an appPackageName that matches your app's package name, and endpointEnabled set to true.
• Make sure the FCM private key file (JSON) you uploaded to Iterable is connected to a Firebase service account associated with the app you're testing.
• Make sure the Firebase service account associated with the FCM private key has permission cloudmessaging.messages.create.
• Make sure that, when you updated your production push integration, that you didn't inadvertently change the FCM message type from Data notifications to Notification messages, or vice-versa.
  • Do not modify this setting in a production project unless you are 100% confident it's the right thing to do. Changing this setting incorrectly can prevent your users from receiving push notifications.
  • To determine the correct FCM message type:
    • Consult your notes from step 2.2.
    • Check with your mobile engineers.
    • Assuming you added the app in question to your sandbox project (above), and that you successfully sent and received a test push notification from that sandbox project, you can check the FCM message type on the app's sandbox push integration.
    • If your app uses Iterable's mobile SDKs, you'll probably use Data notifications.
• From the mobile app definition in your sandbox Iterable project, try sending a test push notification to the same device token. If it arrives, try to determine how the push integration is configured differently in the two projects.

# Appendix: Unassigned push integrations

Some older Iterable projects may have push integrations that aren't assigned to a mobile app (as defined on Settings > Apps and websites). To update these unassigned push integrations to the new FCM HTTP v1 API:

1. Define a mobile app in your Iterable project.
2. Assign the existing push integration to the new mobile app.
3. Update the push integration to use a JSON private key for FCM.

# Step 1: Define a mobile app in your Iterable project

To upgrade an "unassigned" push integration to the new FCM HTTP v1 API, first create a mobile app in your Iterable project. This mobile app app should correspond to a real-world mobile app to which you send push notifications.

To create a mobile app in Iterable:

1. Navigate to Settings > Apps and Websites.

2. Click New app or website. This brings up the New app or website page:

   

3. For Name, enter the name of your app. For example, Example Push Test.

4. For Platform, select Android.

5. For Package name, enter your app's package name. For example, com.example.pushtest.

6. (Optional) For Store URL, enter your app's Play Store URL.

7. Click Create app. You'll be taken to the app's details page:

   

# Step 2: Assign the existing push integration to the new mobile app

After you've created a mobile app, assign the existing, unassigned push integration to it. Don't worry, assigning a push integration to a mobile app doesn't affect the integration's ability to continue sending push notifications.

To associate an existing push integration with your new mobile app:

1. Navigate to Settings > Apps and websites.

2. In the Unassigned Integrations section, at the bottom of the page, find the existing push integration.

3. For that push integration, click Assign App.

4. In the Assign push integration window, select the mobile app you just created.

5. Click Assign.

# Step 3: Update the push integration to use a JSON private key for FCM

Now, to learn how to create private keys for the FCM HTTP v1 API and test them in a sandbox project, and how to update the mobile apps in your production Iterable projects to use those new private keys, follow the steps at the top of this document.