Push Notifications

Push notifications play a central role on your app user engagement.

Offering push notifications is not only nice to have, but mandatory for any app with messaging capabilities.

Upstra offers you two ways to implement push notifications in your app, via webhook or direct push notifications.

Webhook

With this solution live events are fired from Upstra's servers to your servers: once an event is landed on your servers, you have the full power and control on what to do with each notification, including editing/removing/stopping them, way before the notification reaches the your users devices.

In this scenario there's no Android SDK involvement, as the whole notification is managed on your side.

Direct Push Notifications

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

Push Notification Examples

As the Upstra servers are responsible to choose the content of the push notification, you can expect your users to receive the following notifications for different kind 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 user has joined a channel the user is member of. 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 has been received in a channel where the user is member of. 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 to a channel where the user is member of.

  • A new channel is created and the user is among the listed members of the channel on creation.

  • A new member joins a channel where the user is member of.

Initialize Push Notification

FCM dependency:

implementation 'com.github.EkoCommunications.EkoMessagingSDKAndroid:eko-push-fcm:x.y.z'

Before 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 code can be called as much as needed:

EkoFcm.create()
.setup(fcmToken)
.subscribe();

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:

https://push.baidu.com/

Baidu dependency:

implementation 'com.github.EkoCommunications.EkoMessagingSDKAndroid:eko-push-baidu:x.y.z'

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:

EkoBaidu.create()
.setup(baiduApiKey)
.subscribe();

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, Upstra's backend will start sending push notifcations to this particular user. In any cases of active userId changed, The registration is required again.

// you can also listen to successfully/failed states by implementing doOnComplete() and doOnError()
EkoClient.registerDeviceForPushNotification()
.doOnComplete(() -> {
// successfully registered
})
.doOnError(throwable -> {
// failed to register
})
.subscribe();

Client Unregistration

The unregistration allows to pass an optional userId:

  • if a valid userId is passed, Upstra'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, Upstra's backend will stop sending push notifications to this device.

EkoClient.unregisterDeviceForPushNotification(userId)
.subscribe();
EkoClient.unregisterDeviceForPushNotification()
.subscribe();

Client Push Notification Toggles

The SDK has three levels of notifications: to be sent, a notification has to pass throughout all three of them.

The levels are:

  • Network Level (via Admin Panel) turning off notifications at this level effectively disable push notifications alltogether for all your customers.

  • User Level (via client) A user can choose to enable/disable entirely the notifications that it receives (this is a black or white 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 in 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 is member of). Again, this preference is per user, not per device.

User Level Push Notification Toggle

In order to get and set the user level push notifications preference, we use the object EkoUserNotification, obtained from EkoClient:

EkoUserNotification notification = EkoClient.notification();
notification
.isAllowed()
.doOnSuccess(isAllowed -> {
// isAllowed = true => user level enabled
// isAllowed = false => user level disabled
})
.subscribe();
notification
.setAllowed(isAllowed)
.subscribe();

Channel Level Push Notification Toggle

For channel preferences we use the EkoChannelNotification instead, obtained via an instance of EkoChannelRepository or EkoChannel:

EkoChannelNotification notification = channelRepository.notification(channelId);
// or
EkoChannelNotification notification = channel.notification();
notification
.isAllowed()
.doOnSuccess(isAllowed -> {
// isAllowed = true => channel level enabled
// isAllowed = false => channel level disabled
})
.subscribe();
notification
.setAllowed(isAllowed)
.subscribe();