Sendbird Calls SDK for iOS

Table of contents

1. Introduction
2. Before getting started
3. Getting started
4. Configuring the application for the SDK
5. Making your first call
6. Implementation guide
   
7. Appendix
8. Troubleshooting
   

Introduction

Sendbird Calls is the latest addition to our product portfolio. It enables real-time calls between users within a Sendbird application. SDKs are provided for iOS, Android, and JavaScript. Using any one of these, developers can quickly integrate voice and video call functions into their own client apps, allowing users to make and receive web-based real-time voice and video calls on the Sendbird platform.

If you need any help in resolving any issues or have questions, please visit our community

How it works

Sendbird Calls SDK for iOS provides a framework to make and receive voice and video calls. Direct calls in the SDK refers to one-to-one calls. To make a direct voice or video call, the caller specifies the user ID of the intended callee, and dials. Upon dialing, all of the callee’s authenticated devices will receive notifications for an incoming call. The callee then can choose to accept the call from any one of the devices. When the call is accepted, a connection is established between the devices of the caller and the callee. This marks the start of a direct call. Call participants can mute themselves, or call with either or both of the audio and video by using output devices such as speaker and microphone for audio, and front, rear camera for video. A call may be ended by either party. The Sendbird Dashboard displays call logs in the Calls menu for dashboard owners and admins to review.

More about Sendbird Calls SDK for iOS

Find out more about Sendbird Calls for iOS on Calls SDK for iOS doc.

Before getting started

This section shows the prerequisites you need to check to use Sendbird Calls SDK for iOS.

Requirements

• iOS 9.0 or later
• Swift 4 or later, Objective-C
• Xcode 9 or later, macOS Sierra or later.
• Installation of Git Large File Storage

IMPORTANT: MAKE sure to install Git LFS before installing the pod. The size of WebRTC.framework in SendBirdWebRTC folder must be over 800 MB. If the size of the loaded SendBirdWebRTC framework is smaller than 800 MB, check the Git Large File Storage settings and download again. For further details, refer to SDK’s troubleshooting section.

SDK dependencies

• WebRTC framework, which can be integrated by CocoaPods, Carthage, or manual set-up.

Getting started

This section gives you information you need to get started with Sendbird Calls SDK for iOS.

Install Calls SDK

To use Sendbird Calls, first add our custom-built WebRTC framework to the project. Git Large File Storage must be installed to use the WebRTC framework along with the SendBirdCalls framework.

In the project directory, run:

$ brew install git-lfs

$ git lfs install

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. The SendBirdCalls framework can be integrated into the Xcode project using CocoaPods by doing the following.

1. Install CocoaPods into the project by running pod init in the project directory.
2. Run open Podfile
3. In the opened Podfile, include pod 'SendBirdCalls' to the configuration under the project target.
4. Install the SendBirdCalls framework by running pod install in the project directory.

For further details on the usage and installation of CocoaPods instructions, refer to CocoaPods’ website.

Note: The Sendbird Calls SDK for iOS relies on theSendBirdWebRTC framework. SendBirdWebRTC is based on GoogleWebRTC and is recompiled with bitcode enabled. Since SendBirdWebRTC is included in SendBirdCalls as a dependency, it doesn’t need to be explicitly downloaded.

IMPORTANT: After installing the framework, there MUST be a 800+MB SendBirdWebRTC binary inside Pods/SendBirdWebRTC.framework. If not, follow this troubleshooting guide.

Carthage

Carthage is another dependency manager for Xcode projects. The SendBirdCalls framework can be integrated into your Xcode project with Carthage by following these steps:

1. Get Carthage by running brew install carthage, or choose another installation method.
2. Create a Cartfile in the same directory .xcodeproj or .xcworkspace is.
3. List the desired dependencies in the Cartfile as show below. bash github "sendbird/sendbird-calls-ios" ~> 1.6.0 github "sendbird/sendbird-webrtc-ios" ~> 1.3.0
4. Run carthage update.
5. A Cartfile.resolved file and a Carthage directory will appear in the same directory as .xcodeproj or .xcworkspace .
6. Drag the built .framework binaries from Carthage/Build/iOS into the application’s Xcode project.
7. On the application targets’ Build Phases settings tab, click the + icon and choose New Run Script Phase. Create a Run Script that specifies the desired shell (e.g. /bin/sh), then add the following contents to the script area below the shell: bash /usr/local/bin/carthage copy-frameworks
8. Add the paths to the desired frameworks under Input Files. For example: bash $(SRCROOT)/Carthage/Build/iOS/SendBirdCalls.framework $(SRCROOT)/Carthage/Build/iOS/WebRTC.framework
9. Add the paths to the copied frameworks to the Output Files. For example: bash $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/SendBirdCalls.framework $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/WebRTC.framework

Another approach when having multiple dependencies is to use .xcfilelists. This is covered when building for iOS

For an in-depth guide, read on from Carthage’s ReadMe. If you encounter any issues when using Carthage to install the SendBirdCalls, make sure that you are using the latest version of Carthage.

Manual set-up

If you do not prefer to use CocoaPods or Carthage to install Calls SDK, here is an alternative. You can choose to manually integrate SendBirdCalls directly into your project. The SendBirdCalls framework is provided as a fat .framework file and a .xcframework file.

1. Download the framework file by one of the following.
   • Direct download from git releases
   • Git Submodules
   • Other package managers
2. Copy the downloaded framework file into your project directory.
3. Go to General tab of your Xcode Project Navigator, and scroll down to Frameworks, Libraries, and Embedded Content menu.
4. Click the + button, choose Add other… drop down menu, and select Add files… option.
5. From the file navigator, select the framework that you’ve previously downloaded.
6. Select Embed & Sign option in the Embed menu of the selected framework.

Because SendBirdCalls requires SendBirdWebRTC as a dependency, you need to install SendBirdWebRTC as well.

• Navigate to SendBirdWebRTC Repository and perform the above steps 1-6 similarly.

Configuring the application for the SDK

Background Mode

To support background operation, VoIP-enabled apps must have Background Mode enabled in the Xcode Project > Signing & Capabilities pane. Select the checkbox for Voice over IP.

To receive push notifications, the app also must have Push Notifications enabled in the Xcode Project > Signing & Capabilities pane.

For more information about VoIP push notification and PushKit, see Apple’s CallKit and PushKit

Configure the app’s Info.plist File

iOS requires that apps display authorization message to grant the app access to the camera and microphone.

• Microphone-enabled apps must include the NSMicrophoneUsageDescription key in the app’s Info.plist file.
• Camera-enabled apps must include the NSCameraUsageDescription key in the app’s Info.plist file.

Making your first call

Follow the step-by-step instructions below to authenticate and make your first call.

Step 1: Initialize the SendBirdCall instance in a client app

As shown below, the SendBirdCall instance must be initiated when a client app is launched. Initialize the SendBirdCall instance with the APP_ID of the Sendbird application you would like to use to make a call.

SendBirdCall.configure(appId: APP_ID)

Step 2: Authenticate a user and register a push token

In order to make and receive calls, authenticate the user with SendBird server with the SendBirdCall.authenticate(with:) method and register a VoIP push token to Sendbird. Register a VoIP push token by using the SendBirdCall.registerVoIPPush(token:) method after authentication has completed. VoIP Push Notification will also enable receiving calls even when the app is in the background or terminated state. A valid APNS certificate also needs to be registered on the Sendbird Dashboard: Application > Settings > Notifications > Add certificate. For more details on registering push tokens, refer to Calls SDK for iOS doc.

// Authenticate
let params = AuthenticateParams(userId: userId, accessToken: accessToken)
SendBirdCall.authenticate(with: params) { user, error in
    guard let user = user, error == nil else {
        return
    }
    // The user has been authenticated successfully
}

// Update push token
class AppDelegate: PKPushRegistryDelegate {
    func voipRegistration() {
        self.voipRegistry = PKPushRegistry(queue: DispatchQueue.main)
        self.voipRegistry?.delegate = self
        self.voipRegistry?.desiredPushTypes = [.voIP]
    }

    ...
    func pushRegistry(_ registry: PKPushRegistry, didUpdate pushCredentials: PKPushCredentials, for type: PKPushType) {
        SendBirdCall.registerVoIPPush(token: pushCredentials.token, unique: true) { (error) in
            guard let error = error else {
                return
            }
            // The Push Token has been registered successfully
        }
    }
    ...
}

Step 3: Add an event handler

The SDK provides two types of event handlers for various events that client apps may respond to: SendBirdCallDelegate and DirectCallDelegate.

- SendBirdCallDelegate

Register a device-specific SendBirdCallDelegate event handler using the SendBirdCall.addDelegate(:) method. Prior to adding SendBirdCallDelegate, users will be unable to handle the didStartRinging(:) delegate event. It is recommended to add the event handler during initialization because it is a prerequisite for detecting didStartRinging(:) delegate event. SendBirdCallDelegate is removed upon app termination. The code below shows the way device-wide events such as incoming calls are handled once the SendBirdCallDelegate is added.

SendBirdCall.addDelegate(self, identifier: UNIQUE_HANDLER_ID)
func didStartRinging(_ call: DirectCall) {
    // Process incoming call
}

- DirectCallDelegate

Register a call-specific DirectCallDelegate event delegate using call.delegate. Responding to call-specific events, such as establishing a successful call connection, is then managed as shown below.

func didEstablish(_ call: DirectCall)

func didConnect(_ call: DirectCall)

func didEnd(_ call: DirectCall)

func didRemoteAudioSettingsChange(_ call: DirectCall)

func didRemoteVideoSettingsChange(_ call: DirectCall)

func didUpdateCustomItems(call: DirectCall, updatedKeys: [String])

func didDeleteCustomItems(call: DirectCall, deletedKeys: [String])

func didStartReconnecting(_ call: DirectCall)

func didReconnect(_ call: DirectCall)

func didAudioDeviceChange(_ call: DirectCall, session: AVAudioSession, previousRoute: AVAudioSessionRouteDescription, reason: AVAudioSession.RouteChangeReason)

Step 4: Make a call

First, prepare the DialParams call parameter object to initiate a call. The parameter contains the initial call configuration, such as callee’s user id, audio or video capabilities, and CallOptions object. Once prepared, the DialParams object is then passed into the SendBirdCall.dial() method to start the call.

let dialParams = DialParams(calleeId: CALLEE_ID, isVideoCall: false, callOptions: CallOptions(), customItems: [:])

let directCall = SendBirdCall.dial(with: dialParams) { directCall, error in
    //
}

directCall.delegate = self

Step 5: Receive a call

Register SendBirdCallDelegate first to receive incoming calls. Accept or decline incoming calls using the directCall.accept() or the directCall.end() methods. If the call is accepted, a media session will automatically be established by the SDK.

Before accepting any calls, the directCall.delegate must be registered upfront in the SendBirdCallDelegate. Once registered, DirectCallDelegate enables reacting to in-call events through delegate methods.

class MyClass: SendBirdCallDelegate {
    func didStartRinging(_ call: DirectCall) { 
        call.delegate = self
    }
}

Implementation guide

Make a call

First, prepare the DialParams call parameter object to initiate a call. The parameter contains the initial call configuration, such as callee’s user id, audio or video capabilities, and CallOptions object. Once prepared, the DialParams object is then passed into the SendBirdCall.dial() method to start the call.

let dialParams = DialParams(calleeId: CALLEE_ID, isVideoCall: false, callOptions: CallOptions(), customItems: [:])

let directCall = SendBirdCall.dial(with: dialParams) { directCall, error in
    //
}

directCall.delegate = self

Receive a call

Register SendBirdCallDelegate first to receive incoming calls. Accept or decline incoming calls using the directCall.accept() or the directCall.end() methods. If the call is accepted, a media session will automatically be established by the SDK.

Before accepting any calls, the directCall.delegate must be registered upfront in the SendBirdCallDelegate. Once registered, DirectCallDelegate enables reacting to in-call events through delegate methods.

class MyClass: SendBirdCallDelegate {
    func didStartRinging(_ call: DirectCall) { 
        call.delegate = self
    }
}

When the app is in the foreground, incoming call events are received through the SDK’s persistent internal server connection. However, when the app is terminated or in the background, incoming calls are received through PushKit. PushKit messages received by the SendBirdCall must be delivered to the SendBirdCall.pushRegistry(_:didReceiveIncomingPushWith:for:) method.

class MyClass: PKPushRegistryDelegate {
    func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
        SendBirdCall.pushRegistry(registry, didReceiveIncomingPushWith: payload, for: type) { uuid in

            // IMPORTANT: Incoming calls MUST be reported when receiving a pushkit push. 
            let provider = CXProvider(configuration: CXProviderConfiguration)
            let update = CXCallUpdate()
            update.remoteHandle = CXHandle(type: .generic, value: HANDLE_VALUE)
            provider.reportNewIncomingCall(with: uuid, update: update) { error in
                completion()
            })
        }
    }
}

Handle a current call

During an ongoing call, a caller may mute or unmute their microphone by using the directCall.muteMicrophone() or directCall.unmuteMicrophone() methods. DirectCallDelegate.didRemoteAudioSettingsChange() delegate method will notify any changes that a remote user makes on audio settings to the local user.

The caller may start or stop video using the directCall.startVideo() or directCall.stopVideo() methods. If the remote user changes the video settings, the local user will be notified through the DirectCallDelegate.didRemoteVideoSettingsChange() listener. The current video device can be changed by using the directCall.selectVideoDevice(_:completionHandler).

// mute my microphone
call.muteMicrophone();

// unmute my microphone
call.unmuteMicrophone();

// starts to show video
directCall.startVideo();

// stops showing video
directCall.stopVideo();

// changes current video device
directCall.selectVideoDevice(videoDevice) { error in
    // handle error
}

// receives the event
class MyClass: DirectCallDelegate {
    ...
    func didRemoteAudioSettingsChange(_ call: DirectCall) {
        if call.isRemoteAudioEnabled {
            // The peer has been unmuted.            
        } else {
            // The peer has been muted.
        }
    }

    func didRemoteVideoSettingsChange(_ call: DirectCall) {
        if call.isRemoteVideoEnabled {
            // The peer has been unmuted.
        } else {
            // The peer has been muted.
        }
    }
    ...
}

End a call

A caller may end a call using the directCall.end() method. The event will then be processed through the DirectCallDelegate.didEnd(call:) delegate. This delegate is also triggered if the remote user ends the call.

// End a call
call.end();

// receives the event
class MyClass: DirectCallDelegate {
    ...
    func didEnd(_ call: DirectCall) {
        // Consider releasing or destroying call-related view from here.
    }
    ...
}

Deauthenticate a user and unregister a VoIP push token

- Deauthenticate a user

When users log out of their call client apps, they must be deauthenticated with SendBirdCall.deauthenticate(voipPushToken:completionHandler:) method. Failing to include the VoIP push token will result in the logged-out user continually receiving incoming calls despite the app being closed.

class MyClass {
    func signOut() {
        SendBirdCall.deauthenticate(voipPushToken: myVoIPPushToken) { error in
            guard error == nil else {
                // handle error
                return
            }

            // ...
        }
    }
}

- Unregister one or all VoIP push tokens

Users will no longer receive call notifications after the VoIP push token has been unregistered through the unregisterVoIPPush(token:completionHandler:) method. To stop sending notifications to all of the user’s logged in devices, call the unregisterAllVoIPPushTokens(completionHandler:) method.

class MyClass {
    func removeVoIPPushToken() {
        SendBirdCall.unregisterVoIPPush(token: myVoIPPushToken) { error in
        guard error == nil else { return }
        // Unregistered successfully
    }

    func removeAllOfVoIPPushTokens() {
        func unregisterAllVoIPPushTokens(completionHandler: ErrorHandler?) {
            guard error == nil else { return }
            // Unregistered all push tokens successfully
        }
    }
}

Mirror a SendBirdVideoView

You can set the current user’s local video view as mirrored or reversed when the camera is facing the user. In UIView, this can be easily done using the CGAffineTransform(scaleX:y:) method as shown below:

// localSBView is SendBirdVideoView object
localSBView.transform = CGAffineTransform(scaleX: -1.0, y: 1.0)

If you want to reverse the local video view when the user switches the camera from front to back and vice versa, use the following method:

func mirrorLocalVideoView(isEnabled: Bool) {
    guard let localSBView = self.localVideoView?.subviews.first else { return }
    switch isEnabled {
        // Show Mirrored view
        case true: localSBView.transform = CGAffineTransform(scaleX: -1.0, y: 1.0)
        // Show original view
        case false: localSBView.transform = CGAffineTransform(scaleX: 1.0, y: 1.0)
    }
} 


// Flipping camera
self.call.selectVideoDevice(oppositeCamera) { error in
    guard error == nil else { return }

    DispatchQueue.main.async { [weak self] in
        guard let self = self else { return }
        switch oppositeCamera.position {
            case .front: self.mirrorLocalVideoView(isEnabled: true)
            case .back: self.mirrorLocalVideoView(isEnabled: false)
            default: return
        }
    }
}

Retrieve a call information

The local or remote user’s information is available via the directCall.localUser and directCall.remoteUser properties.

Retrieve call history

Sendbird server automatically stores details of calls, which can be retrieved later to display call history for users. A user’s call history is available through a SendBirdCall.DirectCallLogListQuery instance.

let params = DirectCallLogListQuery.Params()
let query = SendBirdCall.createDirectCallLogListQuery(with: params)

query.next(completionHandler: { [weak query] callLogs, error in
    if query?.hasNext == true, query?.isLoading == false {
        // query.next() can be called once more.
        // If a user wants to fetch more call logs.
    }
})

Timeout options

The following table lists a set of methods of the SendBirdCall class.

SendBirdCall.setRingingTimeout(30)

SendBirdCall.setCallConnectionTimeout(30)

Sound effects

- Sound types

Add sound

- addDirectCallSound(_:forType:)

- addDirectCallSound(_:bundle:forType:)

Remove sound

Appendix

Callback and delegate thread handling

Callbacks may be designated to run on specific background threads to keep main threads undisturbed. To specify a thread, run SendBirdCall.executeOn(queue: CUSTOM_QUEUE). Otherwise, SendBirdCall will run asynchronously on DispatchQueue.main.

However, because VoIP PushKit requires immediate and synchronous handling of callbacks, SendBirdCallDelegate.didStartRinging(_) and completion handler of SendBirdCall.pushRegistry(_:didReceiveIncomingPushWith:for:completion:) will run synchronously on the threads that called them. In other words, only these two processes will not run on the thread specified in SendBirdCall.executeOn(queue:).

class AppDelegate: UIResponder, UIApplicationDelegate {

    let callbackQueue = DispatchQueue(label: QUEUE_LABEL)

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Set specific callback queue.
        SendBirdCall.executeOn(queue: self.callbackQueue)

        ...
    }
}

extension AppDelegate: SendBirdCallDelegate {

    func didStartRinging(_ call: DirectCall) {
    // This delegate may not be executed on the thread set by SendBirdCall.executeOn(queue:).
        ...
    }

}

extension AppDelegate: DirectCallDelegate {

    // Runs on the custom thread.
    // In this sample code, runs on the callbackQueue above.
    func didEstablish(_ call: DirectCall) { ... }
    func didConnect(_ call: DirectCall) { ... }
    func didEnd(_ call: DirectCall) { ... }

    ...
}

Call relay protocol

Sendbird Calls is based on WebRTC to enable real-time calls between users with P2P connections, but sometimes connectivity issues may occur for users due to network policies that won’t allow WebRTC communications through Firewalls and NATs (Network Address Translators). For this, Sendbird Calls uses two different types of protocols, Session Traversal Utilities for NAT (STUN) and Traversal Using Relays around NAT (TURN). STUN and TURN are protocols that support establishing a connection between users.

Note: See our GitHub page to learn about the requirements and how to use the Calls SDKs behind a firewall.

How STUN and TURN works

Session Traversal Utilities for NAT (STUN) is a protocol that helps hosts to discover the presence of a NAT and the IP address, which eventually makes the connection between two endpoints. Traversal Using Relays around NAT (TURN) is a protocol that serves as a relay extension for data between two parties.

Sendbird Calls first try to make a P2P connection directly using the Calls SDK. If a user is behind a NAT/Firewall, Calls will discover the host’s public IP address as a location to establish connection using STUN. In most cases, STUN server is only used during the connection setup and once the session has been established, media will flow directly between two users. If the NAT/Firewall still won’t allow the two users to connect directly, TURN server will be used to make a connection to relay the media data between two users. Most of the WebRTC traffic is connected with STUN.

Call results

Encoding Configurations

iOS SDK Sizes

(Xcode 12.3, Any iOS Device (arm64))

- Last Updated: June 18th, 2021

Troubleshooting

Library not loaded WebRTC.framework

This is an example of an error message you may face.

dyld: Library not loaded: @rpath/WebRTC.framework/WebRTC
  Referenced from: /private/var/containers/Bundle/Application/{UUID}/{APPLICATION_NAME}.app/Frameworks/SendBirdCalls.framework/SendBirdCalls
Reason: image not found

Above error is caused by the lack of Git Large File Storage. The size of SendBirdWebRTC.framework is over 800MB. The size of WebRTC binary is about 849MB. However, Git cannot normally download a file that large. To install the entire framework file, installing git-lfs is required. However, because Cocoapods has already cached the faulty SendBirdWebRTC.framework binary, simply installing git-lfs will not solve the problem. All caches associated with SendBirdWebRTC.framework must be cleared. Follow the steps below to clear the caches.

1. Install git-lfs “`bash // in the project directory brew install git-lfs

git lfs install

2. Remove all caches
```bash
pod cache clean --all

rm -rf ~/Library/Caches/CocoaPods/*
rm -rf ~/Library/Developer/Xcode/DerivedData/*

Or, to avoid removing all of the caches not related to SendBirdWebRTC.framework, simply remove caches related to SendBirdWebRTC.framework.

pod cache clean 'SendBirdWebRTC' --all

rm -rf ~/Library/Caches/CocoaPods/Pods/Release/SendBirdWebRTC
rm -rf ~/Library/Caches/CocoaPods/Pods/Specs/Release/SendBirdWebRTC
rm -rf ~/Library/Developer/Xcode/DerivedData/{PROJECT-NAME}-{UUID}

1. Setup Cocoapods again bash pod deintegrate pod setup

1. Re-install Cocoapods dependencies bash pod install