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 CallClient, AudioController and VideoController.

Create the SinchClient

Set up the Sinch client, using SinchClientBuilder:

// Instantiate a SinchClient using the SinchClientBuilder.
android.content.Context context = this.getApplicationContext();
SinchClient sinchClient = Sinch.getSinchClientBuilder();
sinchClient = Sinch.context(context)
                   .applicationKey("<application key>")
                   .environmentHost("ocra.api.sinch.com")
                   .userId("<user id>")
                   .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)

Specify Capabilities

The SinchClient can be configured to enable or disable certain functionality. To enable support for push notifications, use the method SinchClient.setSupportManagedPush(true) for additional steps that are required to fully implement support for push notifications.

The following example shows how to set up the client with voice calling enabled.

// Specify the client capabilities.
sinchClient.setSupportManagedPush(true);

Start the Sinch Client

Before starting the client, add a SinchClientListener:

sinchClient.addSinchClientListener(new SinchClientListener() {

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

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 (mUserId in the following example) 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 implements SinchClientListener {

        @Override
        public void onCredentialsRequired(ClientRegistration registrationCallback) {
            String jwt = JWT.create("<application key>", "<application secret>", mUserId);
            registrationCallback.register(jwt);
        }
}

See section Authentication & Authorization for the details.

Registering the Client / 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() is considered invalid.

Example of how to completely dispose the SinchClient:

sinchClient.terminateGracefully();
sinchClient = null;