User Controller

Push Token Registration via UserController API

info

UserController provides a way, independently from the SinchClient lifecycle, to register a user for incoming calls via push notifications. You can also use it to unregister a push token if receiving incoming calls is no longer desirable (example on logout, or changing users).

Sinch SDK supports both currently available major Push Notification platforms on Android - Google's Firebase Cloud Messages (later FCM Push) and Huawei Mobile Services Push Notifications (later Huawei Push or HMS Push).

UserController provides a way to explicitly register the push token and get assurance that the push token is indeed registered. As an example:

The application is designed to receive calls only and thus must register the push token with the Sinch backend on each start. Even though it's usually best to terminate SinchClient as soon as the registration concludes to free up resources, in this situation, the application should be notified by a specific callback on the registration result.
The application detects that FCM/HMS Push token is invalidated and should be refreshed and re-registered with Sinch backend. Here, if SinchClient is running, it would take care of re-registering of the push token itself, otherwise the application is responsible for re-registering.

Both situations should be handled using the UserController, which can be used independently from the SinchClient (it doesn't require creating and starting the SinchClient).

Create UserController for the Registration for FCM Push

Copy

Copied

public UserController getUserController(String userId) {
     return Sinch.getUserControllerBuilder()
                 .context(getApplicationContext())
                 .applicationKey("<application key>")
                 .userId("<user id>")
                 .environmentHost("ocra.api.sinch.com")
                 .build();
}

Create UserController for the Registration for HMS Push

Copy

Copied

public UserController getUserController(String userId) {
     return Sinch.getUserControllerBuilder()
                 .context(getApplicationContext())
                 .applicationKey("<application key>")
                 .userId("<user id>")
                 .environmentHost("ocra.api.sinch.com")
                 .hms()
                    .deviceToken(hmsDeviceToken)
                    .applicationId(hmsApplicationId)
                    .done()
                 .build();
}

info

Your application can be built to support both Push Notification platforms, but each application instance should register itself towards Sinch backend to receive Push Notification using either one way or another.

info

Please observe that the only difference between FCM and HMS Push registrations is the use of the hms() sub-builder.

The former situation is showcased in LoginActivity.java in sinch-rtc-sample-push and sinch-rtc-sample-video-push sample applications. The activity implements UserRegistrationCallback and PushTokenRegistrationCallback interfaces:

Copy

Copied

public class LoginActivity extends BaseActivity implements SinchService.StartFailedListener, PushTokenRegistrationCallback, UserRegistrationCallback {

    private void loginClicked() {
        ...
        UserController userController = Sinch.getUserControllerBuilder()
                                             .context(getApplicationContext())
                                             .applicationKey("<application key>")
                                             .userId("<user id>")
                                             .environmentHost("ocra.api.sinch.com")
                                             .build();
        userController.registerUser(this, this);
    }

    @Override
    public void onUserRegistrationFailed(SinchError sinchError) {
        dismissSpinner();
        Toast.makeText(this, "Registration failed!", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onUserRegistered() {
        // Instance is registered, but we'll wait for another callback, assuring that the push token is
        // registered as well, meaning we can receive incoming calls.
    }

    @Override
    public void onPushTokenRegistrationFailed(SinchError sinchError) {
        dismissSpinner();
        Toast.makeText(this, "Push token registration failed - incoming calls can't be received!", Toast.LENGTH_LONG).show();
    }

    @Override
    public void onPushTokenRegistered() {
        dismissSpinner();
        startClientAndOpenPlaceCallActivity();
    }

    @Override
    public void onCredentialsRequired(ClientRegistration clientRegistration) {
        // NOTE: This implementation just emulates what should be an async procedure, with JWT.create() being
        // run on your backend.
        clientRegistration.register(JWT.create(<application key>, <application secret>, mUserId));
    }
}

User registration is a two-step process, where the first the step is registering user (after which you can make outgoing calls using the SinchClient), and the second is registering the push token for receiving incoming calls via FCM/HMS Push notifications. Each step has correspondent success and failure callbacks, where you are mostly interested in the tokenRegistered, After receiving it, you can terminate / close the application and be sure that incoming calls will be received.

Token-based User Registration (FCM case)

The action flow diagram of the User registration via UserController is provided below. UserController's callbacks are highlighted in pale blue.

Registering User via UserController

️

User Controller requires signed registration token the same way as it's required by the SinchClient for the first time. Provide it via ClientRegistration.register() callback in response to onCredentialsRequired(). See more information about authentication here.

When both conditions:

SinchClient is started (optional, see the note below)
push token is registered are met, the authentication process has finished and example UI can advance.

info

You don't need to start SinchClient if you only want to receive calls.

info

it's safe to close application right after receiving tokenRegistered() callback - you'll keep receiving incoming calls unless you force stop the application or unregister the push token using UserController.

Push Token Unregistration via UserController API

When you want to logout and stop receiving incoming calls via push, unregister the push token using UserController:

Copy

Copied

    UserController userController = getUserController(<user id>);
    userController.unregisterPushToken();