Migrate from legacy HTTP FCM to FCM HTTP v1

Google retired the legacy Firebase Cloud Messaging (FCM) HTTP API, and Mobile Push Notifications moved Android push from that API to FCM HTTP v1. This guide moves a keyset still configured for legacy HTTP FCM, and still sending pn_gcm payloads, to FCM HTTP v1 and pn_fcm.

Before you start

Confirm you have:

• Admin Portal access to the keyset that has Mobile Push Notifications enabled for Android.
• A Firebase service-account private key file (JSON) for the same Firebase project your app already uses. If you don't have one yet, generate it by following Give PubNub your Firebase credentials.

Migrate with an AI coding assistant

If you use an AI coding assistant, paste this prompt into it to rewrite your push payloads. The prompt makes the assistant read this guide, list every pn_gcm payload first, and ask you to confirm the keyset credential change before it ships new payloads. Do the Admin Portal steps in Update your keyset's FCM credentials yourself.

Migrate this codebase's PubNub Android push payloads from legacy HTTP FCM and
pn_gcm to FCM HTTP v1 and pn_fcm.


1. Read the migration guide first:
   https://www.pubnub.com/docs/migration-guides/legacy-http-fcm.md
   If the PubNub MCP server is connected, you can call get_general_migration_guide
   instead. Where the guide and your own knowledge of PubNub disagree, follow the
   guide and tell me.
2. Before you edit anything, list every place that builds or publishes a pn_gcm
   payload. Then show me a plan and wait for my approval.
3. Before you ship payload changes, ask me to confirm that I replaced the Firebase
   Server Key with the service-account private key file on the keyset in the
   Admin Portal. You can't do that step.
4. Rewrite each pn_gcm payload as pn_fcm. The two structures differ, so don't
   rename the key and reuse its contents. Move Android-specific fields, such as
   content_available and sound, under pn_fcm.android.
5. Make every value inside data a string. pn_fcm rejects numbers, booleans, and
   nested objects there.
6. Don't include topic. PubNub sets it and overwrites any value you supply.
7. If a pn_gcm payload stops producing a notification, rewrite it as pn_fcm.
   Don't adjust the pn_gcm payload further.
8. Make one small change at a time. After each change, run the build and tests
   and show me the output.
9. Never add the Firebase private key file, the PubNub secret key, or any other
   credential to the repository or to client code.
10. When you finish, list every file you changed and the steps left for me.

show all 26 lines

Update your keyset's FCM credentials

1. Open Admin Portal and select the app and keyset that sends Android push.
2. Find the Mobile Push Notifications section.
3. Where you previously pasted a Firebase Server Key, switch to Private key file and upload the JSON key file.
4. Save the keyset.

Update your push payload

Publish messages with a pn_fcm payload instead of pn_gcm. The two objects use different structures, so rewrite the JSON your app publishes rather than only renaming the key.

1{
2  "pn_debug": true,
3  "pn_fcm": {
4    "notification": {
5      "body": "common-body"
6    },
7    "android": {
8      "collapse_key": "group",
9      "data": {
10        "age": "10"
11      },
12      "ttl": "30s",
13      "notification": {
14        "sound": "default"
15      }
16    }
17  }
18}

show all 18 lines

Legacy pn_gcm payloads put content_available and sound directly under notification. Move Android-specific fields under pn_fcm.android instead of renaming pn_gcm and reusing its contents.

Two constraints apply to every pn_fcm payload:

• Every value inside data must be a string. pn_fcm rejects numbers, booleans, and nested objects there.
• Don't include topic. PubNub sets it automatically in the pn_fcm payload and overwrites any value you supply.

Check the FCM payload and Send push notifications on Android cover only the pn_fcm shape. If a pn_gcm payload you send today stops producing a notification, rewrite it as pn_fcm using the mapping above rather than adjusting the legacy payload further.

Related tasks

• Send push notifications on Android. Register a device and send a first pn_fcm push end to end.
• Check the FCM payload. Fix a pn_fcm push that PubNub delivers but that doesn't display or behave as expected.
• Mobile push notifications. The delivery model behind APNs and FCM push, including per-keyset credentials.
• Debug push notification messages. Trace a push failure on the -pndebug channel.