Call client life cycle

The following guide will teach you how to handle the call client lifecycle for the 3.0 version, if you are looking for the 2.x version take a look a this guide instead.

Call client lifecycle

The Kaleyra Video SDK call client is the component responsible for establishing and managing the connection to the Kaleyra Video platform. It's one of the fundamental component of the SDK, and you should have a good understanding about its life cycle and the events it fires to notify its state changes.

Table of contents

• Life cycle
• State changes
• Incoming calls
• What's next

Life cycle

The life cycle of the Kaleyra Video call client is simple and straightforward, you should have little to no problem grasping it. The call client can be seen as a very small finite state machine. It begins its life cycle in the stopped state, transitions to the starting state when you connect the SDK and it moves to the running state when it has successfully connected with the Kaleyra Video platform. While in the running state, the call client can place outgoing calls, receive incoming calls, and it can handle the state of any ongoing call. Whereas, while in any other state, it can't do such things, so outgoing calls cannot be started, incoming calls won't be received, and so on. Easy peasy. The call client has some other intermediate states it can transition to, which you have to take care of. When your app goes in background, the call client is paused automatically, closing any connection to the Kaleyra Video platform (unless there's a call in progress), and it resumes automatically when your app returns in foreground. As you might expect, while in those states the call client cannot perform any task, nor it can receive incoming calls (unless you have integrated VoIP notifications in your app). You don't have to explicitly pause or resume the call client when your app goes in background or returns in the active state, we'll take care of it for you, but you must check the client state and make sure it is running, before asking it to perform any task, otherwise you might get a failure.

State changes

In order to be notified about call client state changes, you can and you should subscribe as a call client observer conforming to the CallClientObserver protocol. This protocol contains a list of optional method you can implement to be notified about call client state changes. The following code listing will show you how to subscribe as an observer to the call client:

func subscribeAsCallClientObserver() {
    BandyerSDK.instance.callClient.add(observer: self, queue: .main)
}

- (void)subscribeAsCallClientObserver
{
    [BandyerSDK.instance.callClient addObserver:self queue:dispatch_get_main_queue()];
}

There are two things to notice here. First, the call client will keep a weak reference to its observers, so if you keep a strong reference the call client you can safely add the client owning object as an observer and you won't get a retain cycle. Second, the call client has two method overloads for adding an object as an observer, the first method is addObserver: (add(observer:)) in swift) the second one is addObserver:queue: (add(observer:queue:)) in swift) (the former is just a convenience method that will call the latter providing a nil queue reference), as stated in our code documentation if you provide a nil queue as the second argument of the addObserver:queue:, your observer will be called synchronously on a background private queue, whereas if you provide a queue as the second argument in the method call, the observer will be called asynchronously on the queue you provided. You must take that into account if you manipulate your UI from one of the observer protocol method.

Incoming calls

You can subscribe as an IncomingCallObserver to get notified when an incoming call is received via WebSocket or VoIP notifications. The IncomingCallObserver protocol lists one method callClient:didReceiveIncomingCall: (callClient(_, didReceiveIncomingCall:) in swift). This method will be called whenever an incoming call is received. You must implement that method if you want to be notified about incoming calls.

func subscribeAsIncomingCallObserver() {
    BandyerSDK.instance.callClient.addIncomingCall(observer: self, queue: .main)
}

- (void)subscribeAsIncomingCallObserver
{
    [BandyerSDK.instance.callClient addIncomingCallObserver:self queue:dispatch_get_main_queue()];
}

What's next

• Making an outgoing call
• Receiving an incoming call