iOS
Calls Remote Notifications

Remote Notifications

Sendbird Calls supports remote notifications to minimize the interruption of a user’s experience while they are using mobile devices. A banner-style notification will appear at the top of the screen when there is an incoming call or an incoming call has been canceled.


Set up

  1. To receive remote notifications in your iOS client app, you must register your APNs certificate from Sendbird dashboard.
  2. Refer to Step 4 of the Install and Configure the Calls SDK section to enable Remote notifications capability.
  3. Register your app with APNs and receive a unique device token by using the registerForRemoteNotifications() method of UIApplication in your AppDelegate.
  4. Deliver incoming notifications from the application(_ :didReceiveRemoteNotification:fetchCompletionHandler:) to the Calls SDK.

Note: You should implement code to show the user interface at the didStartRinging delegate method which is called when the remote notification is delivered.


Remote push token registration

Register

To receive notifications for calls when an app is in the background or closed, a user’s device token must be registered to Sendbird server. To register a device token, call the SendBirdCall.registerRemotePush(token:completionHandler:) method after a user’s authentication has been completed.

To request the current user's device token for remote notifications from AppDelegate, ask appropriate permissions from UNUserNotificationCenter, and call the registerForRemoteNotifications()method of UIApplicationDelegate as shown below. To learn more, see the Apple Developer Documentation's Registering Your App with APNs page.

Light Color Skin
Copy
class AppDelegate: UIResponder, UIApplicationDelegate {
    func remoteNotificationsRegistration(_ application: UIApplication) {
        application.registerForRemoteNotifications()

        let center = UNUserNotificationCenter.current()
        center.requestAuthorization(options: [.alert, .badge, .sound]) { success, error in
            guard error == nil else {   // Error while requesting permission for notifications.
                return
            }

            // If the success is true, the permission is given and notifications will be delivered.
        }
    }
    
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        SendBirdCall.registerRemotePush(token: deviceToken) { error in
            // Handle registering the device token 
        }
    }
}

If the user is not authenticated while the registerRemotePush(token:) method is being called, the registration may not be completed. To avoid this, make sure that you are calling this method after the authentication of the user.

Note: Register a client app for remote notifications in the AppDelegate, and save the returned device token from the application(_: didRegisterForRemoteNotificationsWithDeviceToken:) method to an object for storing data such as UserDefaults. After the authentication of the user, register the saved device token to the SendBirdCall.

Unregister

For a user to stop receiving remote notifications for incoming calls on the device, unregister their device token by using the SendBirdCall.unregisterRemotePush(token:completionHandler:) method.

Light Color Skin
Copy
SendBirdCall.unregisterRemotePush(token: PUSH_TOKEN) { error in
    // Handle unregistration of the current user's device token for remote notifications.
}

Note: Make sure to unregister the device token first, then deauthenticate the user when logging out from Sendbird server.

Unregister All

Use the SendBirdCall.unregisterAllRemotePushTokens(completionHandler:) method to unregister all remote device tokens of the current user.

Light Color Skin
Copy
SendBirdCall.unregisterAllRemotePushTokens { error in
    // Handle unregistration of the current user's all device tokens for remote notifications.
}

Deliver notifications to the SDK

The Calls SDK can process further operations only when the remote notifications related to calls are delivered through the SendBirdCall.application(_:didReceiveRemoteNotification:) method. Like the following, use the method in the application(_:didReceiveRemoteNotification:fetchCompletionHandler:).

Light Color Skin
Copy
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        SendBirdCall.application(application, didReceiveRemoteNotification: userInfo)
}

Note: The Calls SDK will only deliver remote notifications for: an incoming call, an incoming call declined or accepted from another device, an incoming call canceled by the caller, and a missed call. If the call is accepted, the callee will no longer receive notifications regarding the call.


Customize with app extensions

Notification Service app extension

You can customize the content of remote notifications, such as the subject and description, before it is delivered to the user. Implement the didReceive(request:withContentHandler:) method to a Notification Service Extension so that you can access the payload of the remote notifications and customize the content.

It is recommended to use a lightweight UI in your extension because this method only allows up to 30 seconds to process and deliver the notification to the user. For more information, go to the Apple's Notification Service app extension guide.

Notification Content app extension

To show your own content on incoming notifications, add a Notification Content extension target to the Xcode project containing your client app. The default Xcode template contains a source file and storyboard for your view controller. Using a storyboard, you can customize the default notification interface and add interactive controls. Implement didReceive(_ notification: UNNotification) in your view controller for the system to call the method to process incoming notifications. For more information, go to the Apple's Notification Content extension guide.