Calls SDKs Android v1
Calls SDKs Android
Calls SDKs
Android
Version 1

Push notifications

Copy link

A push notification is a message that is immediately delivered to a user device when the device is either idle or running your app in the background. Push notifications for Android client apps are sent using Firebase Cloud Messaging (FCM) and Huawei Mobile Services (HMS) which include custom data your app needs to respond to the notifications. When a call is made to Sendbird server through our Calls SDK for Android, the server communicates with FCM and HMS that will deliver a push notification to an Android device where your app is installed.


Push notifications for FCM

Copy link

There are two types of FCM messages: notification messages and data messages. Sendbird uses data messages, which are handled by the client app. They allow users to customize the message payload, which consists of key-value items.

The following is a set of step-by-step instructions on how to set up push notifications for FCM:

Step 1 Generate private key for FCM

Copy link

Sendbird server requires your private key to send notification requests to FCM on behalf of your server. This is required for FCM to authorize HTTP requests.

Note: If you already have your private key, skip this step and go directly to Step 2: Register private key to Sendbird Dashboard.

  1. Go to the Firebase console. If you don't have a Firebase project for your app, create a new project.

  1. Select your project card to move to the Project Overview.

  2. Click the gear icon at the upper left corner and select Project settings.

  1. Go to Service accounts and click on Generate a new private key.

  1. Go to the General tab and select your Android app to add Firebase to. During the registration process, enter your package name, download the google-services.json file, and place it in your Android app module root directory.

Step 2 Register private key to Sendbird Dashboard

Copy link

Register your private key to the Sendbird server through the dashboard as follows.

  1. Sign in to your dashboard and go to Settings > Application > Push notifications.

  2. Turn on Push notifications and select Send when all devices are offline.

  3. Scroll down to the FCM section and click on Add credentials.

  1. Under Service account key (HTTP v1), upload the JSON file containing the key that was downloaded in Step 1.

Note: Your private key can also be registered using our add an FCM push configuration API.

Step 3 Set up an FCM client app on your Android project

Copy link

Add the following dependency for the Cloud Messaging Android library to your build.gradle file as below:

dependencies {
    ...

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

Note: To learn more about this step, refer to Firebase's Set Up a Firebase Cloud Messaging client app on Android guide. The Google FCM sample project is another helpful reference.

Step 4 Register a registration token to Sendbird server

Copy link

In order to send notification messages to a specific client app on an Android device, FCM requires an app instance's registration token which has been issued by the client app. Therefore, Sendbird server also needs every registration token of your app instances to send notification requests to FCM on behalf of your server.

Note: A user can have up to 20 FCM registration tokens. If a user who already has the maximum number of tokens adds another one, the newest token will push out the oldest, meaning the oldest token will be deleted to add the newest.

Upon the initialization of your app, the FCM SDK generates a unique, app-specific registration token for the client app instance on your user's device. FCM uses this registration token to determine which device to send notification messages to. After the FCM SDK successfully generates the registration token, it is passed to the onNewToken() callback. Registration tokens must be registered to Sendbird server by passing it as an argument to the parameter in the SendBirdCall.registerPushToken() method as shown below.

@Override
public void onNewToken(@NonNull String token) {
    SendBirdCall.registerPushToken(token, false, e -> {
        if (e != null) {
            // Handle error.
            return;
        }
        // Registration tokens successfully registered to Sendbird server.
    });
}

Step 5 Handle an FCM message payload

Copy link

To learn more about how to implement code to receive and parse a FCM notification message, how notification messages are handled depending on the state of the receiving app, how to edit the app manifest, or how to override the onMessageReceived method, refer to Firebase's Receive messages in an Android app guide.

Since different push notifications are received from the Calls SDK or your app through the onMessageReceived() method, you first need to pass the payload to the Calls SDK as shown below to specify which push notifications are from Sendbird Calls. If true, the Calls SDK will parse the payload and otherwise, false will be returned.

@Override
public void onMessageReceived(@NonNull RemoteMessage remoteMessage) {
    if (SendBirdCall.handleFirebaseMessageData(remoteMessage.getData())) {

    } else {
        // Handle push notifications which are not Sendbird Calls push notifications.
    }
}

Push notifications for HMS

Copy link

The following is a set of step-by-step instructions on how to set up push notifications for HMS.

Step 1 Generate app ID and app secret for HMS

Copy link

The Sendbird server requires your app ID and app secret to send notification requests to HMS on behalf of your server. This is required for HMS to authorize HTTP requests.

Note: If you already have your app ID and app secret, skip this step and go directly to Step 2: Register app ID and app secret to Sendbird Dashboard.

  1. Go to the AppGallery Connect. If you don't have a project for a client app, create a new project.

  1. Select your project card to move to Project Settings.

  2. Go to Convention > App Information and copy your App ID and App secret. You will need them on Sendbird Dashboard in Step 2.

  1. During the registration process, enter your package name, download the agconnect-services.json file, and place it in your Android app module's root directory.

Step 2 Register app ID and app secret to Sendbird Dashboard

Copy link

Register your app ID and app secret to the Sendbird server through Sendbird Dashboard as follows.

  1. Sign in to your dashboard and go to Settings > Calls > Push notifications.

  2. Click Add credentials and register the App ID and App secret acquired in Step 1.

Step 3 Set up an HMS client app on your Android project

Copy link

Add the following dependency for the HUAWEI Push Kit Android library to your build.gradle files at both the project and app levels.

allprojects {
    repositories {
            // ...
            maven { url 'https://developer.huawei.com/repo/' }
    }
}

buildscript {
    repositories {
        // ...
        maven { url 'http://developer.huawei.com/repo/' }
    }
    dependencies {
        // ...
        classpath 'com.huawei.agconnect:agcp:1.1.1.300'
    }
}

Step 4 Register a registration token to the Sendbird server

Copy link

In order to send notification messages to a specific client app on an Android device, HMS requires an app instance's registration token which has been issued by the client app. Therefore, the Sendbird server also needs every registration token of client app instances to send notification requests to HMS on behalf of your server.

A user can have up to 20 HMS registration tokens. If a user who already has the maximum number of tokens attempts to add another one, the newest token replaces the oldest.

Upon the initialization of your app, the HMS SDK generates a unique, app-specific registration token for the client app instance on your user's device. HMS uses this registration token to determine which device to send notification messages to. After the HMS SDK has successfully generated the registration token, it is passed to the onNewToken() callback. Registration tokens must be registered to the Sendbird server by passing it as an argument to the parameter in the SendbirdCall.HMS.registerPushToken() method as in the following code.

override fun onNewToken(token: String) {
    SendbirdCall.HMS.registerPushToken(token) { status, e ->
        if (e != null) {
            // Handle error.
        }

        if (status == PushTokenRegistrationStatus.PENDING) {
            // A token registration is pending.
            // Try registering again after a connection has been successfully established.
        }
    }
}

Note: If PushTokenRegistrationStatus.PENDING is returned through the handler, this means that your user isn't being connected to the Sendbird server when SendbirdCall.HMS.registerPushToken() is called. In this case, you must first get a pending registration token using getToken(), and then register the token by calling SendbirdCall.HMS.registerPushToken() in the onSuccess() callback when your user has been connected to the server.

val appId = AGConnectServicesConfig.fromContext(context).getString("client/app_id")
val token = HmsInstanceId.getInstance(context).getToken(appId, "HCM")
SendbirdCall.HMS.registerPushToken(token) { status, e ->
     if (e != null) {
          // Handle error.
     }
          // ...
 }

When the server fails to return a token after a client app has called the getToken() method, it tries to return the token through the onNewToken() method instead as in the following scenario.

  1. After the server has failed to return a token, HUAWEI Push Kit automatically calls the method again, then the server returns the requested token through the onNewToken() method.
  2. If the requested token has expired, the server returns the updated token through the onNewToken() method.
  3. When the EMUI version of a Huawei device is lower than 10.0, the server returns the token through the onNewToken() method.

Step 5 Handle an HMS message payload

Copy link

Different push notifications can be received from both Sendbird Calls SDK and your app through the onMessageReceived() method. To determine which push notifications are from Sendbird Calls, pass the notification payload to the Calls SDK as shown in the snippet below. If true, the Calls SDK parses the payload.

override fun onMessageReceived(remoteMessage: RemoteMessage?) {
   if (SendBirdCall.handleHMSMessageData(remoteMessage.dataOfMap) {
   Log.i(TAG, "[MyHuaweiMessageService] onMessageReceived() => " + remoteMessage.data.toString())
   }
}

Note: See Huawei’s Receive messages in an Android app guide to learn more about how to implement code to receive and parse an HMS notification message, how notification messages are handled depending on the state of the receiving app, how to edit the app manifest, and how to override the onMessageReceived() method.