Edit

Share via

Google Firebase Cloud Messaging migration using REST API and the Azure portal

  • Article

This article describes the core capabilities for the integration of Azure Notification Hubs with Firebase Cloud Messaging (FCM) v1. As a reminder, Google will stop supporting FCM legacy HTTP on June 20, 2024, so you must migrate your applications and notification payloads to the new format before then. All methods of onboarding will be ready for migration by March 1, 2024.

Important

As of June 2024, FCM legacy APIs will no longer be supported and will be retired. To avoid any disruption in your push notification service, you must migrate to the FCM v1 protocol as soon as possible.

Concepts for FCM v1

  • A new platform type is supported, called FCM v1.
  • New APIs, credentials, registrations, and installations are used for FCM v1.

Note

The existing FCM platform is referred to as FCM legacy in this article.

Migration steps

The Firebase Cloud Messaging (FCM) legacy API will be deprecated by July 2024. You can begin migrating from the legacy HTTP protocol to FCM v1 on March 1, 2024. You must complete the migration by June 2024. This section describes the steps to migrate from FCM legacy to FCM v1 using the Notification Hubs REST API.

REST API

The following section describes how to perform the migration using the REST API.

Step 1: Add FCM v1 credentials to hub

The first step is to add credentials via the Azure portal, a management-plane hub operation, or data-plane hub operation.

Create Google service account JSON file

  1. In the Firebase console, select your project and go to Project settings.

  2. Select the Service accounts tab, create a service account, and generate a private key from your Google service account.

  3. Select Generate new private key to generate a JSON file. Download and open the file. Replace the values for project_id, private_key, and client_email, as these are required for Azure Notification Hubs hub credential updates.

    Screenshot of Firebase console project settings.

    OR

    If you want to create a service account with customized access permission, you can create a service account through the IAM & Admin > Service Accounts page. Go to the page directly by clicking Manage service account permissions. You can create a service account that has one of the following roles:

    • Firebase Admin (roles/firebase.admin)
    • Firebase Grow Admin (roles/firebase.growthAdmin)
    • Firebase Admin SDK Administrator Service Agent (roles/firebase.sdkAdminServiceAgent)
    • Firebase SDK Provisioning Service Agent (roles/firebase.sdkProvisioningServiceAgent)

    Screenshot showing IAM service account settings.

Option 1: Update FcmV1 credentials via the Azure portal

Go to your notification hub on the Azure portal, and select Settings > Google (FCM v1). Get the Private Key, Project ID, and Client Email values from the service account JSON file acquired from the previous section, and save them for later use.

Screenshot showing Azure portal Firebase credentials options.

Option 2: Update FcmV1 credentials via management plane hub operation

See the description of a NotificationHub FcmV1Credential.

  • Use API version: 2023-10-01-preview

  • FcmV1CredentialProperties:

    Name Type
    clientEmail string
    privateKey string
    projectId string

Option 3: Update FcmV1 credentials via data plane hub operation

See Create a notification hub and Update a notification hub.

  • Use API version: 2015-01
  • Make sure to put FcmV1Credential after GcmCredential, as the order is important.

For example, the following is the request body:

<NotificationHubDescription xmlns:i='http://www.w3.org/2001/XMLSchema-instance' 
    xmlns='http://schemas.microsoft.com/netservices/2010/10/servicebus/connect'> 
    <ApnsCredential> 
        <Properties> 
            <Property> 
                <Name>Endpoint</Name> 
                <Value>{_apnsCredential.Endpoint}</Value> 
            </Property> 
            <Property> 
                <Name>AppId</Name> 
                <Value>{_apnsCredential.AppId}</Value> 
            </Property> 
            <Property> 
                <Name>AppName</Name> 
                <Value>{_apnsCredential.AppName}</Value> 
            </Property> 
            <Property> 
                <Name>KeyId</Name> 
                <Value>{_apnsCredential.KeyId}</Value> 
            </Property> 
            <Property> 
                <Name>Token</Name> 
                <Value>{_apnsCredential.Token}</Value> 
            </Property> 
        </Properties> 
    </ApnsCredential> 
    <WnsCredential> 
        <Properties> 
            <Property> 
                <Name>PackageSid</Name> 
                <Value>{_wnsCredential.PackageSid}</Value> 
            </Property> 
            <Property> 
                <Name>SecretKey</Name> 
                <Value>{_wnsCredential.SecretKey}</Value> 
            </Property> 
        </Properties> 
    </WnsCredential> 
    <GcmCredential> 
        <Properties> 
            <Property> 
                <Name>GoogleApiKey</Name> 
                <Value>{_gcmCredential.GoogleApiKey}</Value> 
            </Property> 
        </Properties> 
    </GcmCredential> 
    <FcmV1Credential> 
        <Properties> 
            <Property> 
                <Name>ProjectId</Name> 
                <Value>{_fcmV1Credential.ProjectId}</Value> 
            </Property> 
            <Property> 
                <Name>PrivateKey</Name> 
                <Value>{_fcmV1Credential.PrivateKey}</Value> 
            </Property> 
            <Property> 
                <Name>ClientEmail</Name> 
                <Value>{_fcmV1Credential.ClientEmail}</Value> 
            </Property> 
        </Properties> 
    </FcmV1Credential> 
</NotificationHubDescription>

Step 2: Manage registration and installation

For direct send scenarios, proceed directly to step 3. If you're using one of the Azure SDKs, see the SDKs article.

Option 1: Create FCM v1 registration or update GCM registration to FCM v1

If you have an existing GCM registration, update the registration to FcmV1Registration. See Create or update a registration. If you don't have an existing GcmRegistration, create a new registration as FcmV1Registration. See Create a registration. The registration request body should appear as in the following example:

// FcmV1Registration 
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <content type="application/xml">
        <FcmV1RegistrationDescription xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
            <Tags>myTag, myOtherTag</Tags>
            <FcmV1RegistrationId>{deviceToken}</FcmV1RegistrationId>
        </FcmV1RegistrationDescription>
    </content>
</entry> 

// FcmV1TemplateRegistration 
<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom">
    <content type="application/xml">
        <FcmV1TemplateRegistrationDescription xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
            xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
            <Tags>myTag, myOtherTag</Tags>
            <FcmV1RegistrationId>{deviceToken}</FcmV1RegistrationId>
            <BodyTemplate><![CDATA[ {BodyTemplate}]]></BodyTemplate>
        </FcmV1TemplateRegistrationDescription>
    </content>
</entry>

Option 2: Create FCM V1 installation or update GCM installation to FCM v1

See Create or overwrite an installation and set platform to FCMV1.

Step 3: Send a push notification

Option 1: Debug send

Use this procedure to test notifications prior to option 2, 3, or 4. See Notification Hubs - Debug Send.

Note

Use API version: 2023-10-01-preview.

In the header:

Request header Value
Content-Type application/json;charset=utf-8
ServiceBusNotification-Format Set to fcmV1 or template
Servicebusnotification-Tags {single tag identifier}

Test a payload with the following structure via debug send. Note that FcmV1 introduces a significant change in the structuring of the JSON message payload:

  1. The entire payload moved under a message object.
  2. Android-specific options moved to the Android object and time_to_live is now ttl with a string value.
  3. The data field now allows only a flat string-to-string mapping.
  4. For more information, see the FCM reference.

Alternatively, you can perform a test send (debug send) via the Azure portal:

Screenshot showing Azure portal test send page.

Option 2: Direct send

Perform a direct send. In the request header, set ServiceBusNotification-Format to fcmV1.

Option 3: FcmV1 native notification (audience send)

Perform an FcmV1 native notification send. See Send a Google Cloud Messaging (GCM) native notification. In the request header, set ServiceBusNotification-Format to fcmV1. For example, in the request body:

{ 
  "message": { 
    "notification": {  
        "title": "Breaking News",  
        "body": "FcmV1 is ready."  
        }, 
    "android": {  
        "data": {  
            "name": "wrench",  
            "mass": "1.3kg",  
            "count": "3"  
            }  
        } 
    } 
}

Option 4: template notification

You can test template sends with a new request body following the new JSON payload structure. No other changes need to be made. See Send a template notification.

Next steps

Firebase Cloud Messaging migration using Azure SDKs