Skip to content

Commit de5a660

Browse files
author
Jill Grant
authored
Merge pull request #267325 from sethmanheim/fcm-mig
Add updated FCM migration steps
2 parents 33e6278 + c4056e1 commit de5a660

11 files changed

+480
-49
lines changed

‎articles/notification-hubs/TOC.yml

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,15 @@
9595
- name: Security model
9696
href: notification-hubs-push-notification-security.md
9797
- name: How-to guides
98-
items:
98+
items:
99+
- name: FCM migration
100+
items:
101+
- name: Firebase v1 migration guide
102+
href: notification-hubs-gcm-to-fcm.md
103+
- name: FCM migration using REST API and Azure portal
104+
href: firebase-migration-rest.md
105+
- name: FCM migration using Azure SDKs
106+
href: firebase-migration-sdk.md
99107
- name: Change pricing tier
100108
href: change-pricing-tier.md
101109
- name: Send cross-platform notifications

‎articles/notification-hubs/firebase-migration-rest.md

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
---
2+
title: Azure Notification Hubs and the Google Firebase Cloud Messaging (FCM) migration using REST API and the Azure portal
3+
description: Describes how Azure Notification Hubs addresses the Google GCM to FCM migration using REST APIs.
4+
author: sethmanheim
5+
manager: femila
6+
ms.service: notification-hubs
7+
ms.topic: article
8+
ms.date: 03/01/2024
9+
ms.author: sethm
10+
ms.reviewer: heathertian
11+
ms.lastreviewed: 03/01/2024
12+
---
13+
14+
# Google Firebase Cloud Messaging migration using REST API and the Azure portal
15+
16+
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.
17+
18+
## Concepts for FCM v1
19+
20+
- A new platform type is supported, called **FCM v1**.
21+
- New APIs, credentials, registrations, and installations are used for FCM v1.
22+
23+
> [!NOTE]
24+
> The existing FCM platform is referred to as *FCM legacy* in this article.
25+
26+
## Migration steps
27+
28+
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.
29+
30+
## REST API
31+
32+
The following section describes how to perform the migration using the REST API.
33+
34+
### Step 1: Add FCM v1 credentials to hub
35+
36+
The first step is to add credentials via the Azure portal, a management-plane hub operation, or data-plane hub operation.
37+
38+
#### Create Google service account JSON file
39+
40+
1. In the [Firebase console](https://console.firebase.google.com/), select your project and go to **Project settings**.
41+
1. Select the **Service accounts** tab, create a service account, and generate a private key from your Google service account.
42+
1. 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.
43+
44+
:::image type="content" source="media/firebase-migration-rest/firebase-project-settings.png" alt-text="Screenshot of Firebase console project settings." lightbox="media/firebase-migration-rest/firebase-project-settings.png":::
45+
46+
OR
47+
48+
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](https://console.cloud.google.com/iam-admin/serviceaccounts). Go to the page directly by clicking **Manage service account permissions**. You can create a service account that has **Firebase cloud messaging admin access** and use it for your notification hub credential update.
49+
50+
:::image type="content" source="media/firebase-migration-rest/service-accounts.png" alt-text="Screenshot showing IAM service account settings." lightbox="media/firebase-migration-rest/service-accounts.png":::
51+
52+
#### Option 1: Update FcmV1 credentials via the Azure portal
53+
54+
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.
55+
56+
:::image type="content" source="media/firebase-migration-rest/firebase-credentials.png" alt-text="Screenshot showing Azure portal Firebase credentials options." lightbox="media/firebase-migration-rest/firebase-credentials.png":::
57+
58+
#### Option 2: Update FcmV1 credentials via management plane hub operation
59+
60+
See the [description of a NotificationHub FcmV1Credential.](/rest/api/notificationhubs/notification-hubs/create-or-update?view=rest-notificationhubs-2023-10-01-preview&tabs=HTTP#fcmv1credential).
61+
62+
- Use API version: 2023-10-01-preview
63+
- **FcmV1CredentialProperties**:
64+
65+
| Name | Type |
66+
|--------------------|---------------|
67+
| `clientEmail` | string |
68+
| `privateKey` | string |
69+
| `projectId` | string |
70+
71+
#### Option 3: Update FcmV1 credentials via data plane hub operation
72+
73+
See [Create a notification hub](/rest/api/notificationhubs/create-notification-hub) and [Update a notification hub](/rest/api/notificationhubs/update-notification-hub).
74+
75+
- Use API version: 2015-01
76+
- Make sure to put **FcmV1Credential** after **GcmCredential**, as the order is important.
77+
78+
For example, the following is the request body:
79+
80+
```xml
81+
<NotificationHubDescription xmlns:i='http://www.w3.org/2001/XMLSchema-instance'
82+
    xmlns='http://schemas.microsoft.com/netservices/2010/10/servicebus/connect'>
83+
    <ApnsCredential>
84+
        <Properties>
85+
            <Property>
86+
                <Name>Endpoint</Name>
87+
                <Value>{_apnsCredential.Endpoint}</Value>
88+
            </Property>
89+
            <Property>
90+
                <Name>AppId</Name>
91+
                <Value>{_apnsCredential.AppId}</Value>
92+
            </Property>
93+
            <Property>
94+
                <Name>AppName</Name>
95+
                <Value>{_apnsCredential.AppName}</Value>
96+
            </Property>
97+
            <Property>
98+
                <Name>KeyId</Name>
99+
                <Value>{_apnsCredential.KeyId}</Value>
100+
            </Property>
101+
            <Property>
102+
                <Name>Token</Name>
103+
                <Value>{_apnsCredential.Token}</Value>
104+
            </Property>
105+
        </Properties>
106+
    </ApnsCredential>
107+
    <WnsCredential>
108+
        <Properties>
109+
            <Property>
110+
                <Name>PackageSid</Name>
111+
                <Value>{_wnsCredential.PackageSid}</Value>
112+
            </Property>
113+
            <Property>
114+
                <Name>SecretKey</Name>
115+
                <Value>{_wnsCredential.SecretKey}</Value>
116+
            </Property>
117+
        </Properties>
118+
    </WnsCredential>
119+
    <GcmCredential>
120+
        <Properties>
121+
            <Property>
122+
                <Name>GoogleApiKey</Name>
123+
                <Value>{_gcmCredential.GoogleApiKey}</Value>
124+
            </Property>
125+
        </Properties>
126+
    </GcmCredential>
127+
    <FcmV1Credential>
128+
        <Properties>
129+
            <Property>
130+
                <Name>ProjectId</Name>
131+
                <Value>{_fcmV1Credential.ProjectId}</Value>
132+
            </Property>
133+
            <Property>
134+
                <Name>PrivateKey</Name>
135+
                <Value>{_fcmV1Credential.PrivateKey}</Value>
136+
            </Property>
137+
            <Property>
138+
                <Name>ClientEmail</Name>
139+
                <Value>{_fcmV1Credential.ClientEmail}</Value>
140+
            </Property>
141+
        </Properties>
142+
    </FcmV1Credential>
143+
</NotificationHubDescription>
144+
```
145+
146+
### Step 2: Manage registration and installation
147+
148+
For direct send scenarios, proceed directly to step 3. If you're using one of the Azure SDKs, see the [SDKs article](firebase-migration-sdk.md).
149+
150+
#### Option 1: Create FCM v1 registration or update GCM registration to FCM v1
151+
152+
If you have an existing GCM registration, update the registration to **FcmV1Registration**. See [Create or update a registration](/rest/api/notificationhubs/create-update-registration). If you don't have an existing **GcmRegistration**, create a new registration as **FcmV1Registration**. See [Create a registration](/rest/api/notificationhubs/create-registration). The registration request body should appear as in the following example:
153+
154+
```xml
155+
// FcmV1Registration
156+
<?xml version="1.0" encoding="utf-8"?>
157+
<entry xmlns="http://www.w3.org/2005/Atom">
158+
    <content type="application/xml">
159+
        <FcmV1RegistrationDescription xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
160+
<Tags>myTag, myOtherTag</Tags>
161+
            <FcmV1RegistrationId>{deviceToken}</FcmV1RegistrationId>
162+
        </FcmV1RegistrationDescription>
163+
    </content>
164+
</entry>
165+
166+
// FcmV1TemplateRegistration
167+
<?xml version="1.0" encoding="utf-8"?>
168+
<entry xmlns="http://www.w3.org/2005/Atom">
169+
    <content type="application/xml">
170+
        <FcmV1TemplateRegistrationDescription xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/netservices/2010/10/servicebus/connect">
171+
            <Tags>myTag, myOtherTag</Tags>
172+
            <FcmV1RegistrationId>{deviceToken}</FcmV1RegistrationId>
173+
            <BodyTemplate><![CDATA[ {BodyTemplate}]]></BodyTemplate>
174+
        </ FcmV1TemplateRegistrationDescription >
175+
    </content>
176+
</entry>
177+
```
178+
179+
#### Option 2: Create FCM c1 installation or update GCM installation to FCM v1
180+
181+
See [Create or overwrite an installation](/rest/api/notificationhubs/create-overwrite-installation) and set `platform` to `FCMV1`.
182+
183+
### Step 3: Send a push notification
184+
185+
#### Option 1: Debug send
186+
187+
Use this procedure to test notifications prior to option 2, 3, or 4. See [Notification Hubs - Debug Send](/rest/api/notificationhubs/notification-hubs/debug-send?view=rest-notificationhubs-2023-10-01-preview&tabs=HTTP).
188+
189+
> [!NOTE]
190+
> Use API version: 2023-10-01-preview.
191+
192+
In the header:
193+
194+
| Request header | Value |
195+
|--------------------------------------|---------------------------------------|
196+
| `Content-Type` | `application/json;charset=utf-8` |
197+
| `ServiceBusNotification-Format` | Set to `fcmV1` or `template` |
198+
| `Servicebusnotification-Tags` | {single tag identifier} |
199+
200+
Test a payload [with the following structure](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages/send) via debug send. Note that FcmV1 introduces a significant change in the structuring of the JSON message payload:
201+
202+
1. The entire payload moved under a message object.
203+
1. Android-specific options moved to the Android object and `time_to_live` is now `ttl` with a string value.
204+
1. The `data` field now allows only a flat string-to-string mapping.
205+
1. For more information, see [the FCM reference](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages/send).
206+
207+
Alternatively, you can perform a test send (debug send) via the Azure portal:
208+
209+
:::image type="content" source="media/firebase-migration-rest/test-send.png" alt-text="Screenshot showing Azure portal test send page." lightbox="media/firebase-migration-rest/test-send.png":::
210+
211+
#### Option 2: Direct send
212+
213+
Perform a [direct send](/rest/api/notificationhubs/direct-send?view=rest-notificationhubs-2023-10-01-preview). In the request header, set `ServiceBusNotification-Format` to `fcmV1`.
214+
215+
#### Option 3: FcmV1 native notification (audience send)
216+
217+
Perform an FcmV1 native notification send. See [Send a Google Cloud Messaging (GCM) native notification](/rest/api/notificationhubs/send-gcm-native-notification?view=rest-notificationhubs-2023-10-01-preview). In the request header, set `ServiceBusNotification-Format` to `fcmV1`. For example, in the request body:
218+
219+
```json
220+
{
221+
  "message": {
222+
    "notification": {
223+
        "title": "Breaking News",
224+
        "body": "FcmV1 is ready."
225+
        },
226+
    "android": {
227+
        "data": {
228+
            "name": "wrench",
229+
            "mass": "1.3kg",
230+
            "count": "3"
231+
            }
232+
        }
233+
    }
234+
}
235+
```
236+
237+
#### Option 4: template notification
238+
239+
You can test template sends with a new request body following [the new JSON payload structure](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages/send). No other changes need to be made. See [Send a template notification](/rest/api/notificationhubs/send-template-notification?view=rest-notificationhubs-2023-10-01-preview).
240+
241+
## Next steps
242+
243+
[Firebase Cloud Messaging migration using Azure SDKs](firebase-migration-sdk.md)

0 commit comments

Comments
 (0)