Amity Docs (Archived)

V5.0 Documentation

Push Notifications

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

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.

Setup Push Notification Certificate.

In order for Amity's server to start sending push notification to the iOS client , You need to prepare the iOS PSN certification and uploaded to Amity system via Amity Admin panel.

Push Notification Triggers

A new push notification will be sent to a specific user when the following event happens IN a community user a member.

A new post has been created in the community user is a member.
Post owner has been reacted by a user in the community
Post owner has new Comment created by a user in the community.
Comment or Reply owner has been reacted by a user in the community
Comment owner has a new Reply created by a user in the community.

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 kind of events:

A new post has been created in the community user is a member.

Title : CommunityDisplayname

Body : userDisplayname created new post in your community.

Post owner has been reacted by a user in the community

Title : CommunityDisplayname

Body : userDisplayname reacted to your post

Post owner has new Comment created by a user in the community.

Title : CommunityDisplayname

Body : userDisplayname commented to your post

Comment or Reply owner has been reacted by a user in the community

Title : CommunityDisplayname

Body : userDisplayname react to your comment

Comment owner has a new Reply created by a user in the community.

Title : CommunityDisplayname

Body : userDisplayname replied to your comment

Push Notification context customization

as default, all the event related to the Community feature has default context base on each event trigger, to customize the context for each event, you can access to Admin panel to do so.

Client Registration

Before start using push notification, a device token need to be set through registerDeviceForPushNotification(:_)

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    let client: EkoClient!
    
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // Setup EkoClient
        client = EkoClient(apiKey: "YOUR_API_KEY")
    }
    
    // MARK: - Push Notification
    
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        // Prepare device token
        // https://developer.apple.com/documentation/usernotifications/registering_your_app_with_apns
    
        // Transform deviceToken into a raw string, before sending to sdk server.
        let tokenParts: [String] = token.map { data in String(format: "%02.2hhx", data) }
        let tokenString: String = tokenParts.joined()
        
        // Send device token to sdk server
        client.registerDeviceForPushNotification(tokenString)
    }
    
    func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
        // handler error
    }
}

Request push notification authorization

UNUserNotificationCenter
    .current()
    .requestAuthorization(options: [.alert, .sound, .badge]) { granted, _ in
        guard granted else { return }
            DispatchQueue.main.async {
                UIApplication.shared.registerForRemoteNotifications()
            }
        }

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.

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.

// 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
  ...
}

// 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 to observe the completion block outcome to assure of 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 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.
Community Level: (via client) A user can choose to enable/disable notifications for a specific community (where is member of). Again, this preference is per user, not per device.

please note that if the Network level has been disable , the event in the User level AND Community level will be disabled as well.

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:

let userNotificationManager = client.notificationManager

// 1) retrieve settings status 
userNotificationManager.getSettingsWithCompletion { (notification, error) in
    if let notification = notification {
        // handler success
        
        // notification status
        notification.isEnabled
        
        // notification modules which consist of following types
        // - chat
        // - video-streaming
        // - social
        notification.modules
    } else {
        // handle error
    }
}

// 2.1) update settings with enable status
// in case you would like to disable/enable notification for particular module,
// passing `EkoUserNotificationModule` instance that responsible for module settings.
let modules: [EkoUserNotificationModule] = [ EkoUserNotificationModule(moduleType: .social, isEnabled: false, roleFilter: nil)]
userNotificationManager.enableSetting(with: modules) { (success, error) in
    if success {
        // handler success
    } else {
        // handler error
    }
}

// 2.2) update settings with disable status
userNotificationManager.disableSetting() { (success, error) in
    if success {
        // handler success
    } else {
        // handler error
    }
}

EkoUserNotificationsManager *userNotificationManager = notificationManager*self.client.notificationManager;

// 1) retrieve settings status 
[userNotificationManager getSettingsWithCompletion:^(EkoUserNotification * _Nullable notification, NSError * _Nullable error) {
    if (notification) {
        // handler success
        
        // notification status
        notification.isEnabled;
        
        // notification modules which consist of following types
        // - chat
        // - video-streaming
        // - social
        notification.modules;
    } else {
        // handle error
    }
}];

// 2.1) update settings with enable status
// in case you would like to disable/enable notification for particular module,
// passing `EkoUserNotificationModule` instance that responsible for module settings.
NSArray<EkoUserNotificationModule *> *modules = [NSArray arrayWithObject:[[EkoUserNotificationModule alloc] initWithModuleType:EkoNotificationModuleTypeSocial isEnabled:NO roleFilter:nil]];
[userNotificationManager enableSettingWithModules:modules completion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        // handler success
    } else {
        // handler error
    }
}];

// 2.2) update settings with disable status
[userNotificationManager disableSettingWithCompletion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        // handler success
    } else {
        // handler error
    }
}];

Community Level Push Notification Toggle

For Community preferences, we use the EkoCommunityNotificationsManager , obtained via an instance of EkoCommunityRepository:

let communityRepository = EkoCommunityRepository(client: client)
let comunityNotificationManager = communityRepository.notificationManager(forCommunityId: "COMMUNITY_ID")

// 1) retrieve community settings status 
comunityNotificationManager.getSettingsWithCompletion { (notification, error) in
    if let notification = notification {
        // handler success
        
        // notification status
        notification.isEnabled
        
        // notification events which consist of community actions
        notification.events
    } else {
        // handle error
    }
}

// 2.1) update community settings with enable status
// in case you would like to disable/enable notification for particular event,
// passing `EkoCommunityNotificationEvent` instance that responsible for event settings.
let events: [EkoCommunityNotificationEvent] = [ EkoCommunityNotificationEvent(eventType: .postCreated, isEnabled: false, roleFilter: nil) ]
comunityNotificationManager.enableSetting(with: events) { (success, error) in
    if success {
        // handler success
    } else {
        // handler error
    }
}

// 2.2) update community settings with disable status
comunityNotificationManager.disableSetting() { (success, error) in
    if success {
        // handler success
    } else {
        // handler error
    }
}

EkoCommunityRepository *communityRepository = [[EkoCommunityRepository alloc] initWithClient: self.client];
EkoCommunityNotificationsManager *comunityNotificationManager = [communityRepository notificationManagerForCommunityId:@"COMMUNITY_ID"];

// 1) retrieve community settings status 
[comunityNotificationManager getSettingsWithCompletion:^(EkoUserNotification * _Nullable notification, NSError * _Nullable error) {
    if (notification) {
        // handler success
        
        // notification status
        notification.isEnabled;
        
        // notification modules which consist of following types
        // - chat
        // - video-streaming
        // - social
        notification.modules;
    } else {
        // handle error
    }
}];

// 2.1) update community settings with enable status
// in case you would like to disable/enable notification for particular event,
// passing `EkoCommunityNotificationEvent` instance that responsible for event settings.
NSArray<EkoCommunityNotificationEvent *> *events = [NSArray arrayWithObject:[[EkoCommunityNotificationEvent alloc] initWithEventType:EkoCommunityNotificationEventTypePostCreated isEnabled:NO roleFilter:nil]];
[comunityNotificationManager enableSettingWithEvents:events completion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        // handler success
    } else {
        // handler error
    }
}];

// 2.2) update community settings with disable status
[userNotificationManager disableSettingWithCompletion:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        // handler success
    } else {
        // handler error
    }
}];

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 initial

// Unregistration
// A `userId` determines the user of which the SDK should no longer receive notifications.
// It is not required. if nil passed, any push notification associated with the device will be removed.
client.unregisterDevicePushNotification(forUserId: userId) { (userId, success, error) in
   if success {
        // handler success
    } else {
        // handler error
    }
}

PreviousFeed & Timeline NextChangelog

Last updated 3 years ago