search

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.

hashtag
Configuration

Apps must specify the following:

  • 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].** { *; }

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.

hashtag
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)
            .build() )
}

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, Get
Description

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.

changePhoneId() 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.

hashtag
Utility functions

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

User 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 must call this method every time you log in a new user. If the returned result is failure, the user is not considered logged in (trip detection will not behave as expected)

ImsSdkManager.clearIdentity(context: Context)

You must call this method on logout. Clear identity 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, scheduledLogUploaderIntervalHours: UInt)

Heartbeat Function

Sets the interval for heartbeat reporting

setHeartbeatInterval(context: Context, heartbeatIntervalHours: UInt)

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.

hashtag
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