Use KaleyraVideoSDK

The KaleyraVideo represents the main facade of the SDK.

Configure KaleyraVideo SDK

In order to configure the KaleyraVideoSDK correctly the following is required:

• Setup a KaleyraVideo SDK configuration with appId
• Specify an Environment (Production or Sandbox)
• Specify the connection Region
• Pass the configuration as a parameter to the configure method of KaleyraVideo instance.

val configuration = Configuration(
        appId = "mAppId_xxx",
        environment = Environment.Sandbox // Production
        region = Region.Europe // India, US
    )
KaleyraVideo.configure(configuration)

KaleyraVideoService

It is strongly recommended to implement the abstract service KaleyraVideoService in order to be notified whenever the KaleyraVideoSDk needs to be configured and connected.

The implementation of the abstract service KaleyraVideoService is useful for some edge cases such as when the app has been killed from the operating system and then a notification (e.g. kaleyra video or chat notifications) is triggering the app restart but the KaleyraVideo.configure(configuration) and KaleyraVideo.connect(userId) { requestToken(loggedUserId) } methods have not been called.

To implement the abstract service KaleyraVideoService please refer to the following snippet:

<!-- app manifest -->

<service
    android:name=".DemoAppKaleyraVideoService"
    android:exported="false">
        <intent-filter>
            <!-- 
              Do not modify this, the action must be set with value "kaleyra_video_sdk_configure" 
              to let this service be started from the KaleyraVideoSDK
            -->
            <action android:name="kaleyra_video_sdk_configure" />
        </intent-filter>
</service>

// KaleyraVideoService implementation

class DemoAppKaleyraVideoService : KaleyraVideoService() {
    
    override fun onRequestKaleyraVideoConfigure() {
        if (KaleyraVideo.isConfigured) return
        val configuration = Configuration(
            "appId",
            Environment.Production,
            Region.Europe
        )
        KaleyraVideo.configure(configuration)
    }
    
    override fun onRequestKaleyraVideoConnect() {
        KaleyraVideo.connect("userId") { requestToken("userId") }
    }
}

Before Connection

A userID should already exists in our service. Your backend needs to create it by invoking this api create_user

Connect KaleyraVideo SDK

KaleyraVideo SDK can be connected in two ways:

• via access token
• via access link

Important

• The accessToken should be generated from your backend by invoking this api get_credentials. Be aware that it expires. The callback will be called multiple times every time a new token is needed to refresh the user session.
• The accessLink should be generated from your backend by invoking this api create_room. Be aware that it can only be used to enter in a room and when that room is closed/deleted it will automatically expire.

Connecting with an access token

The connect API must be called after that the configure API has been invoked. The token should be provided to the lambda function passed to the connect api as a Result object.

KaleyraVideo.connect("userId") {
    // retrieve asynchronously the user token and then return it as a Result
    Result.success("token")
}

Note that if KaleyraVideo is already connected via access link, connecting via access token with the same user or with another user is not allowed. The current access token session must be ended before connecting again.

Connecting with an access link

KaleyraVideo can optionally be connected using a call url link. The session that will be created using the call url link as access link will last only for the duration of the joined call.

All the sdk feature will be restricted on the call represented by the call link url.

In addition the only chat accessibile will be the chat related to the current call specified by the call link url.

Remember to configure the KaleyraVideoSDK as described here.

To connect via a call url please refer to the following code:

KaleyraVideo.connect("accessLink")

At the end of the call the KaleyraVideoSDK will be automatically disconnected and all persisted data will be cleared as well.

Note that if KaleyraVideoSDK is already connected via access token, connecting via access link with the same user or with another user is not allowed. The current access link session must be ended before connecting again.

Disconnect KaleyraVideo SDK

To disconnect KaleyraVideo invoke the following method:

KaleyraVideo().disconnect();

Reset KaleyraVideo SDK

To reset the configuration and will also disconnect the KaleyraVideo invoke the following method:

KaleyraVideo.reset();

Clear all user data

Call disconnect API with optional boolean parameter set to true to delete all the local data saved for the userAlias used for the KaleyraVideo initialization.

KaleyraVideo.disconnect(clearSavedData = true);

Connection strategy

Kaleyra Video SDK will try to keep the connection alive with Kaleyra remote services as long as the connect api has been called and no disconnect or reset api has been invoked.

This is done by implementing 2 different strategies:

• Token retry strategy
• Infinite reconnect strategy

Token retry strategy

Unless SDK has been connected via access link (since in this case there is no need to refresh tokens), a refresh token mechanism is taking place while the SDK is connected. Every time a new access token is requested in order to refresh the connection or when a token expiration error has been internally received from Kaleyra remote services, the token provider passed to the connect api will be invoked to obtain a new valid token from the integrating app.

If a failure result is passed to the token provider or no success response is received within 15 seconds, 2 other token requests attempts will be executed to prevent momentary errors and obtain anyway a new valid token.

token retry attempt	initial delay time
1	0 seconds
2	1 second + jitter
3	4 seconds + jitter

val jitter = Random.nextLong(LongRange(0L, TimeUnit.SECONDS.toMillis(2)))

A random jitter value between 0 seconds and 2 seconds is added to the delay time between requests in order to minimize side effects serverside when a huge amount of requests could have possibily been received serverside at the same time.

Infinite reconnection strategy

When all the retry attemps to get a new valid token fail, an infinite reconnection strategy takes places in order to reconnect the SDK as soon as possible. Each reconnection attempt is interspersed with a delay calculated with an exponential backoff, in order to minimize transient network errors and preventing to much pressure serverside when a server could not be reached.

At every infinite reconnection strategy attempt a new attemp (+ 2 other extra attempts) to get a new valid token will takes place as shown above.

The following table summarizes what has been said so far.

infinite retry attempt	initial delay time
1	0 seconds
2	3 seconds + jitter
3	9 seconds + jitter
4	27 seconds + jitter
5	60 seconds + jitter
6	120 seconds + jitter

val jitter = Random.nextLong(LongRange(0L, TimeUnit.SECONDS.toMillis(2)))

Following attempts will have a 60 seconds delay as initial delay time.

A random jitter value between 0 seconds and 2 seconds is added to the delay time between requests in order to minimize side effects serverside when a huge amount of requests could have possibily been received serverside at the same time.