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 iOS 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 iOS client has to do in order to display the notification to your users: the Upstra's servers will prepare for you a notification that can be directly displayed to the user.

Push Notification Examples

As Upstra's 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: %1s has joined %2s (%1s = user display name, %2s = channel display name)

  • Event: A new message has been received in a channel where the user is member of. Push Notification Title: %1s (%2s) (%1s = user display name, %2s = 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

Client Registration

Registering your app for push notification will require a registered EkoClient instance (necessary to know which user is associated with this device) and a push notification token.

The Upstra's Development Kit does not manage for you:

  • the user-facing request for push notifications authorization

  • the creation and refresh of a push notification token

It's up to your app to take those steps and pass the notification token to the SDK.

Swift

// assume the client has been initialized with a valid API key and associated to a user
client.registerDeviceForPushNotification(withDeviceToken: token) { [weak self] success, error in
...
}

Objective-C

// assume the client has been initialized with a valid API key and associated to a user
[self.client registerDeviceForPushNotificationWithDeviceToken:token completion:^(BOOL success, NSError * _Nullable error) {
...
}];

We reccomend to observe the completion block outcome to assure of a succesfull registration.

If the device was previously registered with this or another user, the previous registration is invalidated as soon as this new request is received, which means that the device will always receive notifications of up to one user.

Client Unregistration

Unlike the registration, unregistering for push does not require the EkoClient instance to be associated with any user, therefore you can unregister the device from receiving push notifications as soon as the EkoClient has been initialized with a valid API key.

The userId Parameter

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.

Swift

// assume the client has been initialized with a valid API key
// unregister from receiving push notifications for the user with id `userId`
client.unregisterDevicePushNotification(forUserId: userId) { [weak self] _, success, error in
...
}
// unregister from receiving push notifications for this device
client.unregisterDevicePushNotification(forUserId: nil) { [weak self] _, success, error in
...
}

Objective-C

// assume the client has been initialized with a valid API key
// unregister from receiving push notifications for the user with id `userId`
[self.client unregisterDevicePushNotificationForUserId:userId completion:^(NSString * _Nullable, BOOL success, NSError * _Nullable error) {
...
}];
// unregister from receiving push notifications for this device
[self.client unregisterDevicePushNotificationForUserId:nil completion:^(NSString * _Nullable, BOOL success, NSError * _Nullable error) {
...
}];

You can register and unregister as many times as you'd like, however please remember that we use the "Last write wins" strategy.

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 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 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 EkoUserNotificationsManager, obtained from the current EkoClient:

Swift

let pushNotificationManager = client.notificationManager
// get preference
pushNotificationManager.isAllowed { isAllowed, _ in
// isAllowed = true => user level enabled
// isAllowed = false => user level disabled
...
}
// set preference
pushNotificationManager.setIsAllowed(isAllowed) { success, error in
...
}

Objective-C

EkoUserNotificationsManager *notificationManager = self.client.notificationManager;
// get preference
[notificationManager isAllowedWithCompletion:^(BOOL isAllowed, NSError * _Nullable) {
// isAllowed = YES => user level enabled
// isAllowed = NO => user level disabled
...
}];
// set preference
[notificationManager setIsAllowed:YES completion:^(BOOL success, NSError * _Nullable error) {
...
}];

Channel Level Push Notification Toggle

For channel preferences we use the ChannelLevelPushNotificationManager instead, obtained via an instance of EkoChannelRepository:

Swift

let channelRepository = EkoChannelRepository(client: client)
let pushNotificationManager = channelRepository.notificationManager(forChannelId: channelId)
// get preference
pushNotificationManager.isAllowed { isAllowed, error in
// isAllowed = YES => user level enabled
// isAllowed = NO => user level disabled
...
}
// set preference
pushNotificationManager.setIsAllowed(isAllowed) { success, error in
...
}

Objective-C

EkoChannelRepository *channelRepository = [[EkoChannelRepository alloc] initWithClient:self.client];
EkoChannelNotificationsManager *notificationManager = [channelRepository notificationManagerForChannelId:channelId];
// get preference
[notificationManager isAllowedWithCompletion:^(BOOL isAllowed, NSError * _Nullable) {
// isAllowed = YES => user level enabled
// isAllowed = NO => user level disabled
...
}];
// set preference
[notificationManager setIsAllowed:YES completion:^(BOOL success, NSError * _Nullable error) {
...
}];