iOS
Calls Authentication

Authentication

In order to use the features of the Calls SDK in your client apps, user authentication with SendBird server must be initiated through the authenticate() method. To receive calls when an app is in the background or closed, a user’s device token must be registered to the server. A device token can be registered by providing it as a parameter in the authenticate() method when authenticating a user, or by using the SendBirdCall.registerVoIPPush() method after a user’s authentication has been completed.


Initialize the Calls SDK with APP_ID

As shown below, the SendBirdCall instance must be initialized when a client app is launched. Initialization is done by using the APP_ID of your SendBird application in the dashboard. If the instance is initialized with a different APP_ID, all existing call-related data in a client app will be cleared and the SendBirdCall instance will be initialized again with the new APP_ID.

Light Color Skin
Copy
// Initialization
SendBirdCall.configure(appId: APP_ID)

Authenticate to SendBird server

In order to use the interfaces and methods provided in the SendBirdCall instance, a user must be connected to SendBird server by authentication. Without authentication, calling the methods of the Calls SDK will not work in a user’s client app. This means that if a user performs actions such as accepting an incoming call before authentication, the user will receive errors from SendBird server. Also, any other events won’t be received through the Calls SDK if the user isn’t authenticated, except for the incoming calls through CallKit.

For example, the SendBirdCall.authenticate(with:) method should be called before calling the call.accept() in the didFinishLaunchingWithOptions method of your app’s AppDelegate as shown below:

Light Color Skin
Copy
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        SendBirdCall.configure(YOUR_APP_ID)
        SendBirdCall.authenticate(with: authenticateParams) { (user, error) in 
            // 
        }
    }
}

It is recommended to save the current user’s ID to the UserDefaults when a client app launches so that immediate authentication can take place by using the saved user ID.

While using CallKit, if the call.decline() is called before user authentication is completed with SendBird server, a user will receive errors from the server and the CallKit view might hang without response. There are two ways to solve this problem:

1. Call the fulfill() method after user authentication

The fulfill() method should be called within the callback of the SendBirdCall.authenticate() method after the call.decline() is called.

Light Color Skin
Copy
// Authentication
func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
    guard let call = SendBirdCall.getCall(forUUID: action.callUUID) else {
        action.fail()
        return
    }
    SendBirdCall.authenticate(with: authenticateParams) { (user, error) in 
        call.decline()
        action.fulfill()
    }
}

2. Use background modes

Enable background modes by using the beginBackgroundTask() method and call the fulfill() method at the end. Then the Calls SDK will have enough time in the background to complete user authentication and decline an incoming call. This will prevent a client app from being immediately terminated.

Light Color Skin
Copy
func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
    guard let call = SendBirdCall.getCall(forUUID: action.callUUID) else {
        action.fail()
        return
    }
    self.taskId = UIApplication.shared.beginBackgroundTask {
        UIApplication.shared.endBackgroundTask(self.taskId)
    }
    SendBirdCall.authenticate(with: authenticateParams) { (user, error) in 
        call.decline()
    }
    action.fulfill()
}

Deauthenticate from SendBird server

Using the SendBirdCall.deauthenticate(voipPushToken:completionHandler:) method, deauthenticate a user from SendBird server. It will clear all current direct calls, session keys, and user information from a user’s client app. This can also be considered as logging out from the server.

Light Color Skin
Copy
func signOut() {
    SendBirdCall.deauthenticate(pushToken: MY_VOIP_PUSH_TOKEN) { (error) in
        guard error == nil else {   // Error.
            return
        }

        // TODO: Handles the user's deauthentication
    }
}