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"));