Push Notifications

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

Webhook

With this solution, live events are sent from Amity's servers to your servers. Once an event lands on your server, you have full power and control to do whatever you feel is best with each notification; including editing/removing/stopping the notification before it reaches your users devices.

In this scenario, there's no iOS SDK involvement needed. The whole notification process is managed on your end.

Direct Push Notifications

With this solution, the notifications will be triggered and delivered to your users directly by Amity's servers. There's nothing that the iOS client has to do in order to display the notification to your users. Amity's servers will prepare for you a notification that can be directly displayed to the user as and when it's received.

Push Notification Examples

As Amity's servers are responsible for choosing the content of the push notification, 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 other 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. 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 already a member. 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 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.

Client Registration

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

Amity's Development Kit does not manage:

• user-facing requests for push notifications and authorizations

• the creation and refreshing of push notification tokens

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 recommend observing the completion block outcome to ensure a successful 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 AmityClient instance to be associated with any user, therefore you can unregister the device from receiving push notifications as soon as the AmityClient 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, 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.

Swift

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

// unregister from receiving push notifications for this device
client.unregisterDeviceForPushNotification(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 and in order for it to be sent, a notification has to pass throughout all three levels.

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

• User Level: (via client) A user can choose to enable/disable the notifications that it receives on the device (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

To manage the user level push notifications preference, we use the object AmityUserNotificationsManager, obtained from the current AmityClient:

To enable or disable notification for each module, you must create AmityUserNotificationModule.

let pushNotificationManager = client.notificationManager

// Get notification settings
pushNotificationManager.getSettingsWithCompletion { settings, error in
    // ...
}

// Enable/disable notifications for each module.
pushNotificationManager.enable(for: [
    // In this example, we enable "chat", and disable "social" notifications.
    AmityUserNotificationModule(moduleType: .chat, isEnabled: true, roleFilter: nil),
    AmityUserNotificationModule(moduleType: .social, isEnabled: false, roleFilter: nil)
], completion: { success, error in
    // ...
})

// Disable notifications for all modules
pushNotificationManager.disable { success, error in
    // ...
}

Channel Level Push Notification Toggle

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

Swift

Swift

let channelRepository = AmityChannelRepository(client: client)
let pushNotificationManager = channelRepository.notificationManagerForChannel(withId: channelId)

// get notification settings
pushNotificationManager.getSettings { (settings, error) in
  ...          
}

// enable preference
pushNotificationManager.enable { success, error in
  ...
}

// disable preference
pushNotificationManager.disable { 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) {
  ...
}];