Getting Started 2.x

This guide will show you the basic steps you need to make in order to integrate the Kaleyra Video SDK in your iOS app. From now on we are assuming you already have obtained your credentials. This guide will show you how to start integrating the Kaleyra Video iOS SDK 2.x version. If you are looking for the 1.x version guide take a look at the getting started guide for 1.x version instead

The first thing we need to do in order to use the Kaleyra Video iOS SDK is configuring and initializing it. In the code samples below, we are going to initialize the Kaleyra Video iOS SDK in our sample AppDelegate. We do it there for convenience, but you are not required to do so, you can initialize the Kaleyra Video iOS SDK in any point of your code, just make sure to do it only once.

You must create a configuration object the SDK will read to configure itself during initialization. Once this object is created you should start setting the environment in which the SDK will run. In the following examples we tell the SDK to connect to the sandbox environment.

import UIKit
import Bandyer

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        //The sdk needs a configuration object where it is specified which environment the sdk should work in
        let config = Config()

        //Here we are telling the SDK we want to work in a sandbox environment.
        //Beware the default environment is production, we strongly recommend to test your app in a sandbox environment.
        config.environment = .sandbox

        //Here we are disabling CallKit support
        config.isCallKitEnabled = false
        
        //Now we are ready to initialize the SDK providing the app id token identifying your app in Kaleyra Video platform.
    	 //You must provide the APP_ID you got from our sales departement
        BandyerSDK.instance().initialize(withApplicationId: "PUT YOUR APP ID HERE", config: config)
        
        return true
    }

}

//Import the sdk umbrella header
#import <Bandyer/Bandyer.h>

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //The sdk needs a configuration object where it is specified which environment the sdk should work in
    BDKConfig *config = [BDKConfig new];
    
    //Here we are telling the SDK we want to work in a sandbox environment.
    //Beware the default environment is production, we strongly recommend to test your app in a sandbox environment. 
    config.environment = BDKEnvironment.sandbox;
    
    //Here we are disabling CallKit support for the moment.
    config.callKitEnabled = NO;

    //Now we are ready to initialize the SDK providing the app id token identifying your app in Kaleyra Video platform.
    //You must provide the APP_ID you got from our sales departement

    [BandyerSDK.instance initializeWithApplicationId:@"PUT YOUR APP ID HERE" config:config];

    return YES;
}

@end

As you might have noticed, once we set all the flags and configuration needed on the configuration object, we told the SDK to initialize itself providing it an "App Id" and the configuration object created previously. This step, sets up the SDK internally, but you won't start receiving incoming calls nor you can make outgoing calls yet. We must open a user session and start the call client before we can do anything.

Opening an user session

The next step you must perform in order for the SDK to start processing incoming calls and accept outgoing call is open an user session. Once your app user has been authenticated you should open an user session calling the openSession(userId:) method on the BandyerSDK singleton instance providing the "user alias" of the user that is connecting to the Kaleyra Video platform. Beware the "user alias" it's an identifier identifying a particular user on the Kaleyra Video platform; the user alias must exist on the Kaleyra Video platform otherwise the call client won't be able to connect and authenticate with our servers. So do not try to start the client with a dummy value. Let's pretend we are writing an app that has some kind of authentication mechanism. After we have authenticated our user (either she/he has provided hers/his authentication credential on a login screen or we resumed her/his user session) we show her/him our wonderful app main screen. There we are going to open the user session on the BandyerSDK singleton instance.

func onUserAuthenticated(_ userAlias: String) {
    // Once the user has been authenticated and her/his Kaleyra Video user alias has been retrieved
    // We open a session telling it so the BandyerSDK.
    BandyerSDK.instance().openSession(userId: userAlias)
}

- (void)onUserAuthenticated:(NSString *)userAlias
{
    // Once the user has been authenticated and her/his Kaleyra Video user alias has been retrieved
    // We open a session telling it so the BandyerSDK.
    [BandyerSDK.instance openSessionWithUserId:userAlias];
}

When the user signs off don't forget to call the closeSession() method on the BandyerSDK singleton instance. That method will stop any running client and it will close the user session.

Starting the call client

Once the SDK has been initialized and the user session has been opened, you must start the call client in order to be able to receive incoming calls, or make outgoing calls. The call client is the object responsible for connecting to the Kaleyra Video platform, and for making and receiving calls. To start the call client you must call the start method.

class MainViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        //We are registering as a call client observer in order to be notified when the client changes its state.
        //We are also providing the main queue telling the SDK onto which queue should notify the observer provided,
        //otherwise the SDK will notify the observer onto its background internal queue.
        BandyerSDK.instance().callClient.add(observer: self, queue: .main)

        //Then we start the call client.        
        BandyerSDK.instance().callClient.start()
    }
}

@implementation MainViewController

- (void)viewDidLoad
{
    [super viewDidLoad];

    //We are registering as a call client observer in order to be notified when the client changes its state.
    //We are also providing the main queue telling the SDK onto which queue should notify the observer provided,
    //otherwise the SDK will notify the observer onto its background internal queue.
    [BandyerSDK.instance.callClient addObserver:self queue:dispatch_get_main_queue()];

    //Then we start the call client.
    [BandyerSDK.instance.callClient start];
}

@end

As you might have noticed we done two things: we started the call client calling the "start" method on it, but first we registered as a client observer. Any action requested to the call client will be executed asynchronously on a private background queue, so in order to be notified when the client changes it state or when an event is received the first thing you must do is subscribe as a client observer.

Responding to call client events

The call client will notify its observers anytime it changes state or when an incoming call has been received. Let's see if we can connect to Kaleyra Video successfully. We are going to conform the view controller we created to the BDKCallClientObserver protocol. When the client starts successfully the callClientDidStart: method will be invoked. If an error occurs the callClient:didFailWithError: method will be invoked instead.

extension MainViewController: CallClientObserver{
    public func callClientDidStart(_ client: CallClient) {
    	print("Bandyer call client has started")
    }

    public func callClient(_ client: CallClient, didFailWithError error: Error) {
    	print("Bandyer call client has failed because of error \(error)")
    }
}

- (void)callClientDidStart:(id <BDKCallClient>)client
{
   NSLog(@"Bandyer call client has started");
}

- (void)callClient:(id <BDKCallClient>)client didFailWithError:(NSError *)error
{
   NSLog(@"Bandyer call client has failed because of error %@", error);   
}

Where to go from here

Now that you have a basic implementation that can connect to the Bandyer platform you are ready to start making outgoing calls or receive incoming calls. We also recommend you to take a look at the call client lifecycle guide that will explain you how to respond to the call client state change events.

What's next

Looking for other platforms? Take a look at Android, Flutter, ReactNative, Ionic / Cordova. Anything unclear or inaccurate? Please let us know by submitting an Issue or write us here.