Push notifications

Push notifications are messages that are sent to a user's device from a server. They can be used to notify users of new messages, updates, or other important information. In this guide, we'll show you how to implement push notifications in your client app when using the UIKit.

Push notification messages for Android devices will be delivered through Firebase Cloud Messaging service. 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

• Step 2 Register private key to Sendbird Dashboard

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

• Step 4 Register a registration token to the Sendbird server

• Step 5 Handle an FCM message payload

Note: See Push notifications for HMS if you want to see the instructions for HMS push notifications.

The 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 a client app, create a new project.

To view the image in full screen, click on the

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

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

To view the image in full screen, click on the

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

To view the image in full screen, click on the

5. 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.

To view the image in full screen, click on the

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.

To view the image in full screen, click on the

4. 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.

In your root-level (project-level) Gradle file ({project}/build.gradle.kts or {project}/build.gradle), add the Google services plugin as a dependency:

Note: The firebase-messaging version should be 19.0.1 or higher.

plugins {
  id("com.android.application") version "7.3.0" apply false
  // ...

  // Add the dependency for the Google services Gradle plugin
  id("com.google.gms.google-services") version "4.4.2" apply false
}

In your module (app-level) Gradle file (usually {project}/{app-module}/build.gradle.kts or {project}/{app-module}/build.gradle), add the Google services plugin:

plugins {
  id("com.android.application")

  // Add the Google services Gradle plugin
  id("com.google.gms.google-services")
  // ...
}

In your module (app-level) Gradle file (usually {project}/{app-module}/build.gradle.kts or {project}/{app-module}/build.gradle), add the firebase-messaging dependency for the in your app.

dependencies {
  // ...

  implementation("com.google.firebase:firebase-messaging:33.2.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.

The following classes and interface are provided to implement push notifications.

class MyFirebaseMessagingService : SendbirdPushHandler() {
    // This is invoked when a notification message has been delivered to the current user's client app.
    override fun onMessageReceived(context: Context, remoteMessage: RemoteMessage) {
        try {
            val pushTitle = remoteMessage.data["push_title"]
            val message = remoteMessage.data["message"]
            val payload = remoteMessage.data["sendbird"] ?: return
            val sendbirdJson = JSONObject(payload)
            val channelJson = sendbirdJson.getJSONObject("channel")
            val channelUrl = channelJson.getString("channel_url")

            // If you want to customize a notification with the received FCM message,
            // write your method like sendNotification() below.
            sendNotification(context, pushTitle, message, channelUrl)
        } catch (e: JSONException) {
            e.printStackTrace()
        }
    }

    fun sendNotification(context: Context, messageTitle: String?, messageBody: String?, channelUrl: String) {
        // Customize your notification containing the received FCM message.
    }
}

Note: Upon initial startup of your app, the FCM SDK generates a unique and 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.

In order to receive information about push notification events for the current user from Sendbird server, register a MyFireBaseMessagingService instance to SendbirdPushHelper as an event handler. It is recommended to register the instance in the onCreate() method of the Application instance as follows:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        // SendbirdUikitCompose.init
        
        // It must be called after calling SendbirdUikitCompose.init
        SendbirdPushHelper.registerHandler(MyFirebaseMessagingService())
    }
}

Also, register a MyFireBaseMessagingService instance when a user logs into Sendbird server as follows:

SendbirdUikitCompose.connect()
SendbirdPushHelper.registerHandler(MyFirebaseMessagingService())

The instance should be unregistered when a user logs out from Sendbird server as follows:

SendbirdPushHelper.awaitUnregisterHandler()
SendbirdUikitCompose.disconnect()

The Sendbird server sends push notification payloads as FCM data messages, which contain notification-related data in the form of key-value pairs. Unlike notification messages, the client app needs to parse and process these data messages in order to display them as local notifications.

The following code shows how to receive a push notification payload and parse it as a local notification. The payload consists of two properties: message and sendbird. The message property is a string generated according to a push notification template you set on the Sendbird Dashboard. The sendbird property is a JSON object which contains all the information about the message a user has sent. Within MyFirebaseMessagingService.kt, you can show the parsed messages to users as a notification using your custom sendNotification() method.

Note: See Firebase’s Receive messages in an Android app guide 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.

override fun onMessageReceived(remoteMessage: RemoteMessage) {
    try {
        if (remoteMessage.getData().containsKey("sendbird")) {
            val sendbird = JSONObject(remoteMessage.getData().get("sendbird"))
            val channel = sendbird.get("channel") as JSONObject
            val channelUrl = channel["channel_url"] as String
            val messageTitle = sendbird.get("push_title") as String
            val messageBody = sendbird.get("message") as String
            // If you want to customize a notification with the received FCM message,
            // write your method like sendNotification() below.
            sendNotification(context, messageTitle, messageBody, channelUrl)
        }
    } catch (e: JSONException) {
            e.printStackTrace()
    }
}
// ...

fun sendNotification(
    context: Context,
    messageTitle: String,
    messageBody: String,
    channelUrl: String
) {
    // Implement your own way to create and show a notification containing the received FCM message.
    val notificationBuilder = NotificationCompat.Builder(context, channelUrl)
        .setSmallIcon(R.drawable.img_notification)
        .setColor(Color.parseColor("#7469C4")) // small icon background color
        .setLargeIcon(BitmapFactory.decodeResource(context.resources, R.drawable.logo_sendbird))
        .setContentTitle(messageTitle)
        .setContentText(messageBody)
        .setAutoCancel(true)
        .setSound(defaultSoundUri)
        .setPriority(Notification.PRIORITY_MAX)
        .setDefaults(Notification.DEFAULT_ALL)
        .setContentIntent(pendingIntent)
}

The following is a complete payload format of the sendbird property, which contains a set of provided key-value items. Some fields in the push notification payload can be customized in Settings > Chat > Notifications on the Sendbird Dashboard. For example, push_title and push_alert are created based on the Title and Body text you set in Push notification content templates, respectively, in the Notifications menu. In order to display them in a local notification, pass push_title and push_alert of the push notification payload into the setContentTitle and setContentText methods of the NotificationCompat.Builder class, respectively. Also, the channel_unread_count field can be added into or removed from the payload in the same menu on the Sendbird Dashboard.

{
    "category": "messaging:offline_notification",
    "type": string,                         // Message type: MESG, FILE, or ADMM
    "message": string,                          // User input message
    "custom_type": string,                  // Custom message type
    "message_id": long,                      // Message ID
    "created_at": long,                      // The time that the message was created, in a 13-digit Unix milliseconds format
    "app_id": string,                            // Application's unique ID
    "unread_message_count": int,        // Total number of new messages unread by the user
    "channel": {
        "channel_url": string,          // Group channel URL
        "name": string,                      // Group channel name
        "custom_type": string,           // Custom Group channel type
        "channel_unread_count": int // Total number of unread new messages from the specific channel
    },
    "channel_type": string,             // A value of channel_type is set by the system. The value of messaging indicates a distinct group channel while group_messaging indicates a private group channel and chat indicates all other cases.
    "sender": {
        "id": string,                            // Sender's unique ID
        "name": string,                      // Sender's nickname
        "profile_url": string,           // Sender's profile image URL
        "require_auth_for_profile_image": false,
        "metadata": {}
    },
    "recipient": {
        "id": string,                            // Recipient's unique ID
        "name": string                          // Recipient's nickname
    },
    "files": [],                            // An array of data regarding the file message, such as filename
    "translations": {},                      // The items of locale:translation.
    "push_title": string,           // Title of a notification message that can be customized in the Sendbird Dashboard with or without variables
    "push_sound": string,           // The location of a sound file for notifications
    "audience_type": string,                // The type of audiences for notifications
    "mentioned_users": {
        "user_id": string,              // The ID of a mentioned user
        "nickname": string,         // The nickname of a mentioned user
        "profile_url": string,      // Mentioned user's profile image URL
        "require_auth_for_profile_image": false
    },
}

Sendbird’s push notifications with multi-device support provide the same features as our general push notifications, but with additional support for multi-device users. If implemented, notifications are delivered to all online and offline devices of a multi-device user. However, through our Sendbird UIKit for Jetpack Compose, push notifications are displayed only on offline devices, while ignored by online devices. As a result, client apps are able to display push notifications on all offline devices, regardless of whether one or more are online.

For example, let’s say a multi-device user who has six devices installed with your client app is online on one device and offline on the remaining five. If push notifications are implemented, notifications aren’t delivered to any devices. If push notifications with multi-device support are implemented, notifications are delivered to all six devices, but displayed only on the five devices that are offline.

After the above implementation is completed, determine whether multi-device push notification is required for your client app. To set it up, go to Settings > Chat > Push notifications > Push notifications for multi-device users on our dashboard.

To view the image in full screen, click on the

The following table explains when a notification message is sent and whether it is displayed on the device depending on your notification support settings and the device' online status. Refer to the table to find out which notification support best suits the client app use cases.