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.

The Calls SDK will 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.

Note: First, see our GitHub page to learn how to generate your certificate for iOS VoIP Services.

1. To receive remote notifications in your iOS client app, you must register your APNs certificate from Sendbird dashboard.
2. Refer to the Make 1-to-1 call 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.

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.

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 {
                // Handle error while requesting permission for notifications.
            }

            // 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
            guard error == nil else {
                // Handle error.
            }

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

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.

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.

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

SendBirdCall.unregisterAllRemotePushTokens { (error) in
    // Handle unregistration of the current user's all device tokens for remote notifications.
}

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:).

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

Note: By default, application(_:didReceiveRemoteNotification:fetchCompletionHandler:) delegate method isn’t called if the client app is in the background or closed. When a remote push notification is delivered to the mobile device, the notification will show as a banner and won’t trigger the delegate method while the app is in the background. If the client app is closed, the payload will be delivered when the user responds to the notification by tapping on it. However, if the client app is in the foreground, the notification will trigger the delegate method immediately.

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.

To show your own content on incoming notifications, add a Notification Content extension target to the Xcode project containing your 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.