Integrate offline push

Follow this guide to integrate and test push notifications in your environment.

Before proceeding, ensure that you meet the following requirements:

• You have initialized the Chat SDK. For details, see SDK quickstart.
• You understand the call frequency limit of the Chat APIs supported by different pricing plans as described in Limitations.

This section guides you through integrating FCM with Chat. W

Note

For Android devices, if FCM and push services from other manufacturers are enabled at the same time, FCM push services will be used first.

1. Log in to the Firebase console and add a project.

2. Register the application in the project.

   In the Download and then add config file step of the Add Firebase to your Android app page, click Download google-services.json and put the file into your Android app module root directory.

   

3. Query the sender ID. On the Project settings page, select the Cloud Messaging tab and view Sender ID. When uploading the FCM certificate to Agora Console, set the certificate name to the FCM sender ID.

   

4. On the Project settings page, select the Service accounts tab and click Generate new private key to generate a JSON file. Save this file and upload it to Agora Console when using the V1 certificate.

   

After successfully logging into Chat, you can upload the FCM push certificate to Agora Console:

1. Log in to Agora Console, and click Project Management in the left navigation bar.

2. On the Project Management page, locate the project that has Chat enabled and click Config.

3. On the project editing page, click Config next to Chat.

4. On the project config page, select Features > Push Certificate and click Add Push Certificate.

5. In the pop-up window, select the Google tab, and configure the following fields:

   

   Parameter	Type	Required	Description
   Certificate Type		No	Select whether to use a V1 certificate or a legacy certificate. V1: Recommended. You need to configure a Private Key. Legacy: Will soon be deprecated. You need to configure a Push Key.
   Private Key	file	Yes	Click Generate new private key on the Project settings > Service accounts page of the Firebase Console to generate the .json file, then upload it to Agora Console.
   Push Key	String	Yes	FCM Server Key. Obtain the server key in the Cloud Messaging API (Legacy) area of the Project settings > Cloud Messaging page of the Firebase Console. This parameter is only valid for legacy certificates.
   Certificate Name	String	Yes	The sender ID configured for the FCM. For the new version of the certificate, you can find the sender ID on the Project settings > Cloud Messaging page of the Firebase Console. For legacy certificates, go to the *Project settings > Cloud Messaging page of the Firebase Console, and get the sender ID in the Cloud Messaging API (Legacy) area. The certificate name is the only condition used by the Agora server to determine which push channel the target device uses, so ensure that the sender set when integrating FCM in Chat is consistent with what is set here.
   Sound	String	No	The ringtone flag for when the receiver gets the push notification.
   Push Priority		No	Message delivery priority. See Setting the priority of a message.
   Push Msg Type		No	The type of the message sent to the client through FCM. See Message types: Data: Data message, processed by the client application. Notification: Notification message, automatically processed by FCM SDK. Both: Notification messages and data messages can be sent through the FCM client.

The legacy HTTP or XMPP API is being retired on June 20, 2024. In view of this, switch to the latest FCM API (HTTP v1) version of the certificate as soon as possible. See Firebase Console for details.

Make sure that the uploaded V1 certificate is available, as the legacy one will be deleted upon upload. If the new certificate is not available, the push will fail.

Take the following steps to switch from the old to the new certificate:

1. Click Edit in the Action column of the old certificate on the Push Certificate page.

   

2. In the Google tab of the Edit Push Certificate window, switch the Certificate Type to V1.

   

3. Click Upload to upload the locally saved V1 certificate file (.json).

   

4. Click OK to complete the switch.

Take the following steps to integrate FCM on the client.

1. In the build.gradle file of your app project, configure the FCM library dependency:

   
   

   _13

   plugins {

   _13

   id 'com.android.application'

   _13

   // Add the Google services Gradle plugin

   _13

   id 'com.google.gms.google-services'

   _13

   }

   _13

   dependencies {

   _13

   // ...

   _13

   // Import the Firebase BoM

   _13

   implementation platform('com.google.firebase:firebase-bom:28.4.1')

   _13

   // Declare FCM dependency

   _13

   // When using BoM, do not specify versions in Firebase library dependencies

   _13

   implementation 'com.google.firebase:firebase-messaging'

   _13

   }

   
   

   In your <project>/build.gradle file, configure the following:

   
   

   _5

   plugins {

   _5

   // ...

   _5

   // Add the dependency for the Google services Gradle plugin

   _5

   id 'com.google.gms.google-services' version '4.3.15' apply false

   _5

   }

   
   

   For Gradle 5.0 and above, BoM is automatically enabled; for versions prior to Gradle 5.0, you need to enable it. For details, see Firebase Android BoM and Firebase Android SDK Release Notes.

2. Sync your project with gradle files, extend FirebaseMessagingService, and register it in the AndroidManifest.xml file of your project:

   
   

   _19

   public class FCMMSGService extends FirebaseMessagingService {

   _19

   private static final String TAG = "FCMMSGService";

   _19

   _19

   @Override

   _19

   public void onMessageReceived(RemoteMessage remoteMessage) {

   _19

   super.onMessageReceived(remoteMessage);

   _19

   if (remoteMessage.getData().size() > 0) {

   _19

   String message = remoteMessage.getData().get("alert");

   _19

   Log.d(TAG, "onMessageReceived: " + message);

   _19

   }

   _19

   }

   _19

   _19

   @Override

   _19

   public void onNewToken(@NonNull String token) {

   _19

   great . onNewToken(token);

   _19

   Log.d(TAG, "onNewToken: " + token);

   _19

   ChatClient.getInstance().sendFCMTokenToServer(token);

   _19

   }

   _19

   }

   
   
   
   

   _7

   <service

   _7

   android:name=".FCMMSGService"

   _7

   android:exported="false">

   _7

   <intent-filter>

   _7

   <action android:name="com.google.firebase.MESSAGING_EVENT" />

   _7

   </intent-filter>

   _7

   </service>

   
   

3. Initialize the Chat SDK and enable FCM:

   
   

   _25

   ChatOptions options = new ChatOptions();

   _25

   ...

   _25

   PushConfig.Builder builder = new PushConfig.Builder(this);

   _25

   // Replace with your FCM Sender ID.

   _25

   builder.enableFCM("Your FCM sender id");

   _25

   // Configure push settings in the ChatOptions class.

   _25

   options.setPushConfig(builder.build());

   _25

   // Initialize the IM SDK.

   _25

   ChatClient.getInstance().init(this, options);

   _25

   // Set up push monitoring.

   _25

   PushHelper.getInstance().setPushListener(new PushListener() {

   _25

   @Override

   _25

   public void onError(PushType pushType, long errorCode) {

   _25

   EMLog.e("PushClient", "Push client occur a error: " + pushType + " - " + errorCode);

   _25

   }

   _25

   @Override

   _25

   public boolean isSupportPush(PushType pushType, PushConfig pushConfig) {

   _25

   // Set whether to enable FCM.

   _25

   if(pushType == PushType.FCM) {

   _25

   return GoogleApiAvailabilityLight.getInstance().isGooglePlayServicesAvailable(MainActivity.this)

   _25

   == ConnectionResult.SUCCESS;

   _25

   }

   _25

   return super.isSupportPush(pushType, pushConfig);

   _25

   }

   _25

   });

   
   

4. Pass the FCM device token to the server.

   When the app is initialized, the FCM SDK generates a unique registration token for the client app on the user's device. Since FCM uses this token to determine which device to send the push message to, the Agora server needs to obtain the client app's registration token before sending the notification request to FCM. FCM then verifies the registration token and sends the notification message to the Android device. It is recommended to place this code on the main page after successfully logging into Chat.

   
   

   _17

   // Check if FCM is enabled.

   _17

   if(GoogleApiAvailabilityLight.getInstance().isGooglePlayServicesAvailable(MainActivity.this) != ConnectionResult.SUCCESS) {

   _17

   return;

   _17

   }

   _17

   FirebaseMessaging.getInstance().getToken().addOnCompleteListener(new OnCompleteListener<String>() {

   _17

   @Override

   _17

   public void onComplete(@NonNull Task<String> task) {

   _17

   if (!task.isSuccessful()) {

   _17

   EMLog.d("PushClient", "Fetching FCM registration token failed:"+task.getException());

   _17

   return;

   _17

   }

   _17

   // Get the FCM registration token, i.e., the device token.

   _17

   String token = task.getResult();

   _17

   EMLog.d("FCM", token);

   _17

   ChatClient.getInstance().sendFCMTokenToServer(token);

   _17

   }

   _17

   });

   
   

5. Monitor device token generation.

   After the FCM SDK successfully generates a registration token (device token), it will be passed to the onNewToken callback.

   Rewrite the onNewToken callback in FirebaseMessagingService. After the device token is generated, this callback will promptly update the new token to the Chat SDK.

   
   

   _8

   @Override

   _8

   public void onNewToken( @NonNull String token) {

   _8

   Log.i("MessagingService", "onNewToken: " + token);

   _8

   // To send messages to the app or manage app subscriptions on the server, you need to send the FCM registration token to your App Server.

   _8

   if(ChatClient.getInstance().isSdkInited()) {

   _8

   ChatClient.getInstance().sendFCMTokenToServer(token);

   _8

   }

   _8

   }

   
   

After integrating and enabling FCM, you can test whether the push feature is successfully integrated.

Make sure your test device meets the following conditions:

• Uses foreign IP addresses to establish connections.
• Supports Google GMS services (Google Mobile Services).
• Can access Google network services; otherwise, the device won't be able to receive push notifications from the FCM service.

For more reliable testing, use a physical device.

1. Log in to the app on your device and confirm that the device token is successfully bound.

   You can check the log or call RESTful API for getting user details to confirm whether the device token is successfully bound. If successful, there will be a pushInfo field under the entities field, and pushInfo will have relevant information such as device_Id, device_token, notifier_name, and others.

2. Enable app notification bar permissions.

3. Kill the application process.

4. Send a test message in the Agora Console.

   Select Operation Management > User in the left navigation bar. On the Users page, select Send Admin Message in the Action column for the corresponding user ID. In the dialog box that pops up, select the message type, enter the message content, and then click Send .

   Note

   In the Push Certificate page, in the Action column of each certificate, click More and Test will appear. This is to directly call the third-party interface to push. The message sending test in the Users page first calls the Chat message sending interface and then the third-party interface when the conditions are met (that is, the user is offline, the push certificate is valid and bound to the device token).

5. Check your device to see if it has received the push notification.

In case of issues, take the following steps:

1. Check whether FCM push is correctly integrated or enabled:

   Select Operation Management > User in the left navigation bar. On the User Management page, select Push Certificate in the Action column for the corresponding user ID. In the pop-up box, check whether the certificate name and device token are displayed correctly.

2. Check whether the correct FCM certificate is uploaded in the Agora Console.

3. Check whether the message is pushed in the chat room. The chat room does not support offline message push.

4. Check if the device supports GMS.

5. Check whether online-only delivery is enabled (deliverOnlineOnly = true). Messages set to be delivered only when the receiver is online will not be pushed.