Sinch Client

The Sinch SDK is a product that makes adding voice and video calling to mobile apps easy. Continue reading this step-by-step guide now.

The SinchClient is the Sinch SDK entry point. it's used to configure the user’s and device’s capabilities, as well as to provide access to feature classes such as the CallController, AudioController and VideoController.

Create the SinchClient

Set up the Sinch client, using SinchClientBuilder:

val sinchClient = SinchClient.builder()
                   .context(context)
                   .applicationKey("<application key>")
                   .environmentHost("ocra.api.sinch.com")
                   .userId("<user id>")
                   .pushConfiguration(pushConfiguration)
                   .build()

• The Application Key is obtained from the Sinch Developer Dashboard - Apps .
• The User ID should uniquely identify the user on the particular device.
• (The term Ocra in the hostname ocra.api.sinch.com is just the name for the Sinch API that the SDK clients target)
• The Push Configuration is a configuration object that allows Sinch SDK to send push messages notifying about incoming calls. See push noficiation section for more information about this feature.

Start the Sinch Client

Before starting the client, add a SinchClientListener:

sinchClient.addSinchClientListener(object: SinchClientListener() {

    override fun onClientStarted(client: SinchClient) { }
    override fun onClientFailed(client: SinchClient, error: SinchError) { }
    override fun onCredentialsRequired(clientRegistration: ClientRegistration) {
      // You have to implement this method, it can't be no-op.
    }
    override fun onLogMessage(level: Int, area: String, message: String) { }
})

sinchClient.start()

When starting the client (sinchClient.start()) the client will ask for a token via SinchClientListener.onCredentialsRequired(). See section Authentication & Authorization for the details.

Authorizing the Client / User

When the SinchClient is started with a given User ID it's required to provide an authorization token to register towards the Sinch backend. To authorize a client, implement SinchClientListener.onCredentialsRequired() that's cryptographically signed with the Application Secret.

The sample applications included in the Sinch SDK includes a class JWT that describes how to create the JWT and sign it with the Application Secret.

class MySinchClientListener: SinchClientListener() {

        override fun onCredentialsRequired(clientRegistration: ClientRegistration) {
            val jwt = JWT.create(APP_KEY, APP_SECRET, userName)
            clientRegistration.register(jwt)
        }
}

See section Authentication & Authorization for the details.

Registering the user via UserController API

You can also register a user towards the Sinch backend via UserController API. This lightweight component provides a way to register the user without starting the SinchClient. You can also register push token for Managed Push to receive incoming calls even when the application is closed/in background. The UserController uses the very same authentication scheme as the SinchClient based on the signed JWT registration token that you provide in response to onCredentialsRequired() method of UserRegistrationCallback. The UserController provides better control over the registration process than the SinchClient by providing callbacks for each step of the registration.

Lifecycle management of a SinchClient instance

We recommend that you initiate the SinchClient, start it, but not terminate it, during the lifetime of the running application. That also implies that the SinchClient instance should be retained by the application code. It's best to keep the client instance alive and started unless there are reasons specific to your application.

The SinchClient can of course be completely stopped and also disposed.

When the app is done using the SinchClient, it can be stopped and disposed using SinchClient.terminateGracefully().

Example of how to completely dispose the SinchClient:

sinchClient?.terminateGracefully()
sinchClient = null