Initialize the SDK

The SDK needs to be configured with some basic settings before it is used.

Configuration is a one-time operation; the SDK remembers its configuration and, once configured, initializes itself automatically.

Configuration

Apps must specify the following:

  • API Key: IMS provides each customer with a unique API key during the enrollment process. A valid key is required to use the SDK and to connect to IMS DriveSync servers. This is the same API key used in your custom Identity class.

  • SDK Folder: The directory the SDK will use for data storage and logs. We recommend that this folder be excluded from Auto Backup.

  • Token Signer class: The host app is responsible for providing the SDK with the class for a TokenSigner object that generates a signed JSON Web Token to be used by the SDK when connecting to IMS servers. The token signer class must have a no-argument constructor and should not be obfuscated. You should to add a line like this to your proguard-rules file : -keep class [MyTokenSigner].** { *; }

  • Identity: The host app shares the identity of its currently authenticated user by providing an Identity object to the SDK. The identity is persisted through app restarts, so you only need to specify when it changes (usually when the user logs in).

Apps may specify the following:

  • WiFi Only upload flag: By default the SDK uploads data using WiFi if available or the cell network if not. You may want to restrict uploads to WiFi only or make this a user-specified option.

  • Log Upload interval: The SDK uses log files to track its performance and health as well as to assist with troubleshooting. These files are automatically uploaded at the end of each trip. By default logs are also uploaded once every 24 hours. You may wish to do this more frequently or disable it completely.

  • Heartbeat interval: The Heartbeat service is used to provide the server with regular information about the state of each phone, whether or not any trips are reported. The hearbeat service is disabled by default.

Getting and setting the SDK configuration

SDK configuration is accessed through the global ImsSdk object.

Sample code for configuring the SDK:

if (!ImsSdkManager.isConfigured) {
    ImsSdkManager.setSdkConfiguration( context,
        ImsSdkManager.Builder()
            .setApiKey("TEST_API_KEY")
            .setSdkFolder(File(context.filesDir, "ims_sdk"))
            .setTokenSigner(MyTokenSigner::class.java)
            .setHeartbeatInterval(HEARTBEAT_INTERVAL)
            .setUploadWiFiOnly(true)
            .setIdentity(myUserIdentity)
            .build() )
}

There are also shortcuts for some common settings.

ImsSdkManager.setIdentity(context, myUserIdentity)
ImsSdkManager.setUploadWiFiOnly(context, true)

Apps control the SDK using the ImsSdkManager object. Configuration is normally set through ImsSdkManager.Builder, but ImsSdkManager also supports changing some properties on their own.

Note that all getters are read-only.

Set, GetDescription

setApiKey() apiKey

IMS provides each customer with a unique API key during the enrollment process. A valid key is required to use the SDK and to connect to IMS DriveSync servers. This is the same API key used in your custom Identity class.

setSdkFolder() rootFolder

The directory the SDK will use for data storage and logs. We recommend that this folder be excluded from Auto Backup.

setTokenSigner() tokenSigner

The host app is responsible for providing the SDK with the class for a TokenSigner object that generates a signed JSON Web Token to be used by the SDK when connecting to IMS servers.

setUploadWiFiOnly() isUploadWiFiOnly

By default the SDK uploads data using WiFi if available or the cell network if not. You may want to restrict uploads to WiFi only or make this a user-specified option.

setLogUploadInterval() logUploadInterval

The SDK uses log files to track its performance and health as well as to assist with troubleshooting. These files are automatically uploaded at the end of each trip. By default logs are also uploaded once every 24 hours. You may wish to do this more frequently or disable it completely by setting the interval to 0.

setHeartbeatInterval() heartbeatInterval

The Heartbeat service is used to provide the server with regular information about the state of each phone, whether or not any trips are reported. Heartbeat interval is in hours; specify 0 (default) to disable it.

setIdentity() identity

The host app shares the identity of its currently authenticated user by providing an Identity object that the SDK persists through app restarts.

--- phoneId

The SDK generates a unique identifier for each phone. This is used internally for trip recording and other functions. Although there's no technical reason to change the phone identifier, some customers prefer to use a new ID every time a different user logs in. In that case you can use ImsSdk.changePhoneId() to generate a new identifier.

Utility functions

ImsSdkManager provides methods for setting and getting the SDK configuration plus some utility functions.

User Identity

ImsSdkManager.setIdentity(contex: Context, identity: Identity?) The host app shares the identity of its currently authenticated user by providing an Identity object that the SDK persists through app restarts. You should call this method every time you log in a new user, and clear it when logging out.

Upload Mode

ImsSdkManager.setUploadWiFiOnly(context: Context, isUploadWiFiOnly: Boolean) By default the SDK uploads data using WiFi if available or the cell network if not. You may want to restrict uploads to WiFi only or make this a user-specified option.

Diagnostic Mode

ImsSdkManager.setDiagnosticMode(isDiagnosticMode: Boolean) Enables a special diagnostic mode with additional SDK log messages and internal checks. Should only be used for developement and troubleshooting, not in production.

Log Listener

ImsSdkManager.addLogListener(logListener: DsLogListener) Adds a listener the SDK logging framework. This is useful if you want to include SDK log messages in your own custom logger, and/or if you want to add them to Crashlytics as custom log messages.

Automatic Log Uploads

ImsSdkManager.setLogUploadInterval(context: Context,

Heartbeat Function

Change Phone ID

ImsSdkManager.changePhoneId(context: Context) The SDK generates a unique identifier for each phone. This is used internally for trip recording and other functions. Although there's no technical reason to change the phone identifier, some customers prefer to use a new ID every time a different user logs in. In that case you can generate a new identifier.

Errors and Warnings

ImsSdkManager validates its configuration every time it's set or changed. If there's a code-related problem it throws an exception so that programmers can detect and fix the problem early in the development cycle.

The error messages are designed to be informative; in most cases they provide links directly to the relevant section in these documents.

Some of these errors are:

PreviousObfuscationNextUsing the SDK

Last updated