Set up push notifications for FCM
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.
Note: See Push notifications for HMS if you want to see the instructions for HMS push notifications.
Step 1 Generate private key for FCM
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.
- Go to the Firebase console. If you don't have a Firebase project for a client app, create a new project.
-
Select your project card to move to the Project Overview.
-
Click the gear icon at the upper left corner and select Project settings.
- Go to Service accounts and click on Generate a new private key.
- 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
Register your private key to the Sendbird server through the dashboard as follows.
-
Sign in to your dashboard and go to Settings > Application > Push notifications.
-
Turn on Push notifications and select Send when all devices are offline.
-
Scroll down to the FCM section and click on Add credentials.
- 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
Add the following dependency for the Cloud Messaging Android library to your build.gradle
file.
Note: The firebase-messaging version should be 19.0.1 or higher.
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 the Sendbird server
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, the Sendbird server also needs every registration token of client app instances to send notification requests to FCM on behalf of your server.
A user can have up to 20 FCM 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 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 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 registerPushToken()
method as in the following code.
Note: If
PushTokenRegistrationStatus.PENDING
is returned through the handler, this means that your user isn't being connected to the Sendbird server whenregisterPushToken()
is called. In this case, you must first get a pending registration token usinggetToken()
, and then register the token by calling theregisterPushToken()
method in theonSuccess()
callback when your user has been connected to the server.
Step 5 Handle an FCM message payload
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.
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.