Enterprise Communications APIGet StartedReference
Reference
Select ProductPortal

Initialise

To initialise the SDK, there are pre-requisites:

  • A configured API space.
  • An authentication provider that can generate a JWT that matches the auth scheme configured for your API space.

You set both of these when building the configuration object. This is the only required configuration setup. To use the SDK you must also provide event listeners.

ComapiConfig config = new ComapiConfig()
   .apiSpaceId("<API_SPACE_ID>")
   .authenticator(new ChallengeHandler());

Example of the authentication challenge handler:

Must extend the ComapiAuthenticator class.

public class ChallengeHandler extends ComapiAuthenticator {
    @Override
    public void onAuthenticationChallenge(AuthClient authClient, 
       ChallengeOptions options) {
          authClient.authenticateWithToken(/*get token using options.getNonce()*/));
    }
}

🚧

onCreate in Application

The initialisation must be performed in the onCreate method of the Android Application class.

You can use APIs in two versions: reactive and with callbacks. The Callback version initialises through the Comapi class and the access to APIs is through ComapiClient.

For a reactive Java alternative, use RxComapi and RxComapiClient classes.

public class MyApplication extends Application {

    @Override
    public void onCreate()
    {
        super.onCreate();
      
        Comapi.initialiseShared(this, config, new Callback<ComapiClient>() {
            @Override
            public void success(ComapiClient client) {
               //Use client instance to communicate with services
            }

            @Override
            public void error(Throwable t) {
               //Error
            }
        });
    }
}

public class MyApplication extends Application {

    @Override
    public void onCreate()
    {
        super.onCreate();
      
        RxComapi.initialiseShared(this, config)
           .subscribeOn(Schedulers.io())
           .observeOn(AndroidSchedulers.mainThread())
           .subscribe(new Action1<RxComapiClient>() {
                    @Override
                    public void call(RxComapiClient client) {
                       //Use client instance to communicate with services
                    }
                }, new Action1<Throwable>() {
                    @Override
                    public void call(Throwable t) {
                        //Error
                    }
                });
    }
}

Both of the above calls create singleton client instances that you can obtain through get singleton:

Comapi.getShared(); 
// OR
RxComapi.getShared();

If you don't want the SDK to keep the reference to the client instance use non-singleton init instead and store the client yourself:

Comapi.initialise(...);
// OR
RxComapi.initialise(...);

Add listeners

When your app is in the foreground it keeps the socket connection open and listens for live updates of your profile, and any conversations for which you are a participant.

Register for the incoming events with the ComapiConfig object and pass it to registration method.

ComapiConfig config = new ComapiConfig()
   .apiSpaceId("<API_SPACE_ID>") //required
   .authenticator(new ChallengeHandler()) //required
   .pushMessageListener(/* extends PushMessageListener */)
   .messagingListener(/* extends MessagingListener */)
   .profileListener(/* extends ProfileListener */)
   .stateListener(/* extends StateListener */);

Advanced options

FCM

If you don't want the SDK to manage FCM registration and token, disable FCM:

config.fcmEnabled(false);

Logging

You can set the logging level separately for internal file and console output and network calls to OFF, FATAL, ERROR, WARNING, INFO, DEBUG. By default they are set to warning.

ComapiConfig config = new ComapiConfig().logConfig(
new LogConfig()
   .setFileLevel(LogLevel.DEBUG)
   .setConsoleLevel(LogLevel.DEBUG)
   .setNetworkLevel(LogLevel.DEBUG));

You can also set custom limits for the size of internal log files:

new ComapiConfig().logSizeLimitKilobytes(limit);

Proxy

If your test app connects through a proxy, provide the URI:

new ComapiConfig().apiConfiguration(new APIConfig()
       .proxy("http://xx.xxx.xx.xxx:xxxx"));