Push Notifications
Ensure that your users don’t miss important content from each other.

Webhook

With this solution live events are sent from Amity's servers to your servers: once an event lands on your servers, you have the full power and control on what to do with each notification, including editing/removing/stopping the notification before it reaches your users devices.
In this scenario there's no Android SDK involvement, as the whole notification is managed on your end.

Direct Push Notifications

With this solution, the notifications are triggered and delivered to your users directly by Amity's servers. There's nothing that the Android client has to do in order to display the notification to your users: Amity's servers will prepare a notification that can be directly displayed to the user.

Push Notification Examples

As the Amity servers are responsible for choosing the content of the push notifications, you can expect your users to receive the following notifications for different kinds of events:
    Event: New channel has been created and the user has been added among its members. Push Notification Title: %s (%s = New Channel display name) Push Notification Body: You're now member of %s! (%s = New Channel display name)
    Event: A new member joins a channel of the user who is already an existing member of it
    Push Notification Title: %s (%s = user display name) Push Notification Body: %1$s has joined %2$s (%1$s = user display name, %2$s = channel display name)
    Event: A new message is sent in a channel of the user who is already an existing member of it. Push Notification Title: %1$s (%2$s) (%1$s = user display name, %2$s = channel display name) Push Notification Body: %s (%s = message text body if text message, Image Message if image message, Special message otherwise)

Push Notification Triggers

A new push notification will be sent to a specific user when:
    A new message is sent in a channel of the user who is already an existing member of it
    A new channel is created and the user is among the listed members of the channel on creation
    A new member joins a channel of the user who is already an existing member of it

Initialize Push Notification

FCM dependency:
1
implementation 'com.github.AmityCo.Amity-Social-Cloud-SDK-Android:amity-push-fcm:x.y.z'
Copied!
Before you can start receiving push notifications, you need to obtain a FCM unique token string that identifies each FCM client app instance:
You can initialize the services with the obtained token. Please note that the FCM token can be changed through application life cycle. Please make sure that the FCM token supplied to the messaging SDK is up to date. To notify the messaging SDK of the latest token, the following line of code can be called whenever necessary:
1
AmityFcm.create()
2
.setup(fcmToken)
3
.subscribe();
Copied!

Retrieve Push Notifications

To retrieve push notifications, use a service that extends FirebaseMessagingService. Refer to Firebase's messages handling documentation for the detailed information.

Push Notification In China

Since Google play services are banned in China, The messaging SDK provides Baidu push services as a substitute for FCM. The messaging SDK requires an api key and a secret key from Baidu:
Baidu dependency:
1
implementation 'com.github.AmityCo.Amity-Social-Cloud-SDK-Android:amity-push-baidu:x.y.z'
Copied!
Note: Baidu push services require number of additional permissions. You can find a list of permissions here.
Baidu API key is needed for Baidu push services initialization:
1
AmityBaidu.create()
2
.setup(baiduApiKey)
3
.subscribe();
Copied!
Note: The messaging SDK always consider FCM as a primary push provider and Baidu as a secondary push provider. If the messaging SDK detects Google play services on the device, Baidu push services won't be initialized.

Client Registration

The registration will automatically pick up the active userId, and Amity's back-end will start sending push notifications to the particular user. In the where where the active userId has been changed, registration will be required again.
1
// you can also listen to successfully/failed states by implementing doOnComplete() and doOnError()
2
3
AmityCoreClient.registerDeviceForPushNotification()
4
.doOnComplete(() -> {
5
// successfully registered
6
})
7
.doOnError(throwable -> {
8
// failed to register
9
})
10
.subscribe();
Copied!

Client de-registration

The de-registration allows you to pass an optional userId:
    if a valid userId is passed, Amity's backend will stop sending push notifications to this device only if the currently active push notification associated with this device is also associated with that user. No action is taken otherwise.
    if no userId is passed, Amity's backend will stop sending push notifications to this device.
1
AmityCoreClient.unregisterDeviceForPushNotification(userId)
2
.subscribe();
3
4
AmityCoreClient.unregisterDeviceForPushNotification()
5
.subscribe();
Copied!

Client Push Notification Toggles

The SDK has three levels of notifications. To be sent, a notification has to pass throughout all three levels to be successfully delivered.
The levels are:
    Network Level (via Amity Social Cloud Console) Turning off notifications at this level effectively disables push notifications for all of your customers.
    User Level (via client) A user can choose to entirely enable/disable the notifications that they receive (this is an absolute option: enable all or disable all). Please note that this setting is per user, not per device: regardless of which device sets this toggle, the new preference will take effect on all the devices where the user is logged in.
    Channel Level (via client) A user can choose to enable/disable notifications for a specific channel (where the user is a member). Again, this preference is per user, not per device.

User Level Push Notification Toggle

To get and set the user level push notifications preference, we use the object AmityUserNotification, obtained from AmityCoreClient:
1
val notification = AmityCoreClient.notification()
2
3
notification
4
.isAllowed()
5
.doOnSuccess(isAllowed -> {
6
// isAllowed = true => user level enabled
7
// isAllowed = false => user level disabled
8
})
9
.subscribe()
10
11
notification
12
.setAllowed(isAllowed)
13
.subscribe()
Copied!

Channel Level Push Notification Toggle

For channel preferences we use the AmityChannelNotification instead, obtained via an instance of AmityChannelRepository or AmityChannel:
1
val notification = channelRepository.notification(channelId)
2
// or
3
val notification = channel.notification()
4
5
notification
6
.getSettings()
7
.doOnSuccess(settings -> {
8
// settings.isEnabled = true => channel level enabled
9
// settings.isEnabled = false => channel level disabled
10
})
11
.subscribe()
12
13
notification
14
.enable()
15
.subscribe()
16
//or
17
notification
18
.disable()
19
.subscribe()
Copied!
Last modified 3d ago