NIM SDK 4.6.0 and later versions support Firebase Cloud Messaging (FCM).

FCM is a push service launched by Google, which supports overseas users to push notifications and provides a wide range of messaging functions.

Google FCM is an enhanced version of GCM and is well-suited for users located overseas. FCM push service requires two essential conditions:

• The phone installs and successfully runs Google Mobile Services (GMS).
• The mobile phone must be connected to overseas networks.

• On some mobile phones, even when both of the aforementioned conditions are met and FCM push service is successful, the push notification may not be displayed.
• If your app primarily serves users in Mainland China, FCM integration is not necessary.

This article introduces how to access the push channel of FCM so that messages can be delivered to users who are not online through FCM.

Integrate FCM

Step 1: Create a Firebase project and register the app

If you have already registered your app on the Firebase platform, ignore this step. For more information about FCM, see push service guide.

1. Use a Google account to log in to Firebase.

2. Create a Firebase project in the Firebase console.

   Procedure

   1. In the Firebase console, click Add Project.
      • To add Firebase resources to an existing Google Cloud project, enter the project name or select the project from the drop-down menu.
      • To create a new project, enter the project name. You can also choose to edit the project ID that appears below the project name.
   2. If prompted, review and accept the Firebase Terms and click Continue.
   3. Click Create project. If using an existing Google Cloud project, click Add Firebase.

   Firebase automatically configures resources for your Firebase project. Once the process is complete, you'll be redirected to your Firebase project's overview page in the Firebase console.

3. Register the app in the Firebase project.

   Procedure

   1. In the Firebase console, on the Firebase project's overview page, click Add App or the Android icon ().
   2. After entering the relevant information of the Android application, click Register App.

Step 2: Configure the FCM certificate in the CommsEase console

Provide the service account authorization credentials of the FCM project and manually upload the credentials to the CommsEase console.

CommsEase supports two authorization methods:

• (New) private key file in JSON format

  1. In the Firebase console, open Settings -> Service accounts.
  2. Click Generate new private key.
  3. Save the generated JSON file.

  

• (Legacy) Server key

  1. In the Firebase console, open Settings -> Service accounts.
  2. Record the Server key.

  

• Starting from March 2020, FCM stops creating legacy server keys. For more information, see Authorize legacy protocol send requests and Migrate from legacy FCM APIs to HTTP v1.
• Starting from v9.11.0, CommsEase supports the new version of FCM push certificate. If you need to upload the new version of FCM push certificate, contact sales or technical support.

Upload the obtained credentials to the CommsEase console:

1. In the Applications section in the CommsEase console, click the application you want to configure the certificate, go to Settings > Certificates.

2. Click Add Certificate under Android Push Certificate, select the certificate type as Google(FCM), and configure the FCM certificate.

CommsEase field	Firebase application field
Certificate name	User-defined push certificate name, up to 32 characters Corresponds to fcmCertificateName in the push certificate information required for initializing the NIM SDK
App package name	the package name of the Firebase application, up to 1,000 characters
AppSecret	the Firebase application's Server secret, a maximum of 5,000 characters

1. According to the interface prompts, configure the certificate type, certificate name and other information in the dialog box.

Step 3: Add Firebase configuration file

1. Register the application in the Firebase project and click Download google-services.json file.

2. Add the configuration file to the app root directory of the application.

3. To enable Firebase, add google-services plugin to the Gradle file.

   • Configure Google's Maven code base in the project-level Gradle file (build.gradle) to import the Google Service Gradle plugin.

   javabuildscript {
   
   repositories {
     // Make sure that you have the following two repositories
     google()  // Google's Maven repository
     mavenCentral()  // Maven Central repository
       }
   
   dependencies {
     ...
   
     // Add the dependency for the Google services Gradle plugin
     classpath 'com.google.gms:google-services:4.3.15'
       }
   }
   
   allprojects {
   ...
   
   repositories {
       // Make sure that you have the following two repositories
       google()  // Google's Maven repository
       mavenCentral()  // Maven Central repository
       }
   }
   

   • In the application-level Gradle file (app/build.gradle), add Firebase dependencies and FCM dependencies.

   javaplugins {
   id 'com.android.application'
   
   // Add the Google services Gradle plugin
   id 'com.google.gms.google-services'
   ...
   }
   

Step 4: Import FCM SDK

1. In the application-level Gradle file (app/build.gradle), add Firebase dependencies and FCM dependencies.

   javadependencies {
   // firebase-messaging
   implementation 'com.google.firebase:firebase-messaging:23.0.0'
   // firebase-analytics 
   implementation 'com.google.firebase:firebase-analytics:20.0.0'
   }
   

   NIM SDK is compatible with the following FCM versions :

   javaimplementation 'com.google.firebase:firebase-messaging:23.0.0'
   implementation 'com.google.firebase:firebase-analytics:20.0.0'
   

2. Sync your app to ensure all dependencies have the required versions.

Step 5: Configure AndroidManifest.xml

In the app/src/main folder, open the AndroidManifest.xml file and add required permissions.

xml<!-- fcm -->
<service android:name="com.netease.nimlib.mixpush.fcm.FCMTokenService">
    <intent-filter>
        <action android:name="com.google.firebase.INSTANCE_ID_EVENT" />
    </intent-filter>
</service>

You can also set the icon and font color displayed when receiving FCM messages.

xml    android:resource="@drawable/Replace with your notification icon" />
<meta-data
    android:name="com.google.firebase.messaging.default_notification_color"
    android:resource="@color/Change the font color" />

4. If your application uses code obfuscation, include the following configuration in your proguard-rules.pro file to ensure that the FCM SDK code remains unobfuscated:

java-dontwarn com.google.**
-keep class com.google.** {*;}

Google FCM platform restrictions

Message types

Using FCM, you can send two types of messages to clients:

• Notification messages, sometimes thought of as "display messages." These are handled by the FCM SDK automatically.
• Data messages, which are handled by the client app.

Notification messages contain a predefined set of user-visible keys. Data messages, by contrast, contain only your user-defined custom key-value pairs. Notification messages can contain an optional data payload. Maximum payload for both message types is 4000 bytes, except when sending messages from the Firebase console, which enforces a 1000 character limit.

Message type	Use scenario	How to send
Notification message	FCM SDK displays the message to end-user devices on behalf of the client app when it's running in the background. Notification messages have a predefined set of user-visible keys and an optional data payload of custom key-value pairs.	1. In a trusted environment such as Cloud Functions or your app server, use the Admin SDK or the HTTP v1 API. Set the notification key. May have optional data payload. Always collapsible. See some examples of display notifications and send request payloads. 2. Use the Notifications composer: Enter the Message Text, Title, etc., and send. Add optional data payload by providing Custom data.
Data message	Client app is responsible for processing data messages. Data messages have only custom key-value pairs with no reserved key names.	In a trusted environment such as Cloud Functions or your app server, use the Admin SDK or the FCM Server Protocols. In the send request, Set the data key.

Configure types of push notifications

To ensure that push notifications alert users, configure the "android_channel_id" for push notification types. This configuration can be achieved through the "pushPayload" in the message body of the NIM SDK.

Sample code:

java// fcmField structure
//     "fcmField": {
//         "android_channel_id":""
//     }

pushPayload.put("pushTitle", "Set push title here");
pushPayload.put("fcmField", fcmField);

When sending a message to the FCM push platform, the following logic applies:

• If the pushPayload in the message body includes the "android_channel_id" field, the value specified in the "android_channel_id" field within the pushPayload will be used as the message type.
• If the pushPayload of the message body does not include the android_channel_id field, the system will use the default message type (android_channel_id="0"). If you need to change the default message type, contact your account manager or technical support.

Customize push notifications

In the pushPayload field of the message body IMMessage of NIM SDK, a key can be configured as fcmField, whose value is an Entry of map or JSONObject, implementing push configurations such as titles and icons. For more information, see FCM documentation.

Sample code:

java{
  "title": string, //The notification's title
  "body": string,//The notification's body text
  "icon": string,//The notification's icon.
  "color": string,//The notification's icon color
  "sound": string,//The sound to play when the device receives the notification.
  "tag": string,//Identifier used to replace existing notifications in the notification drawer.
  "click_action": string,//The action associated with a user click on the notification.
  "image": string,//the URL of an image that is going to be displayed in a notification.
  ...
}

Set message priority

You have two options available for assigning the delivery priority of downstream messages: Normal priority and High priority. While the behavior varies slightly across platforms, normal and high priority messages are delivered as follows:

• Normal priority Normal-priority messages are delivered immediately when the application is in the foreground. For background applications, there may be some delay in message delivery. This priority is suitable for less time-sensitive messages, such as new email notifications, UI synchronization, or background data synchronization.
• High priority FCM attempts to deliver high priority messages immediately, even if the device is in doze mode. High priority messages are primarily used for time-sensitive content that requires immediate user attention.

Upstream message limit

• limit upstream messages at 1,500,000/minute per project to avoid overloading upstream destination servers.
• limit upstream messages per device at 1,000/minute to protect against battery drain from bad app behavior.

Topic message limit

The topic subscription add/remove rate is limited to 3,000 QPS per project. For information about message delivery rate, see fanout throttling.