Android

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 TokenSignerobject 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].** { *; }. How to implement Token Signer see https://sdk.ims.tech/security.

· 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,
    new ImsSdkManager.Builder()
      .setApiKey(“API_KEY”)
      .setSdkFolder(new File(context.getFilesDir(), "ims_sdk"))
      .setTokenSigner(MyTokenSigner.class)
      .build()
  ); 
}

There are also shortcuts for some common settings.

ImsSdkManager.setIdentity(contex: Context, identity: Identity?)

ImsSdkManager.setUploadWiFiOnly(context: Context, isUploadWiFiOnly: Boolean)

ImsSdkManager.setDiagnosticMode(isDiagnosticMode: Boolean)

ImsSdkManager.addLogListener(logListener: DsLogListener)

ImsSdkManager.changePhoneId(context: Context)

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 and setters are read-only.

Set, Get	Description
setApiKey()	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 Identityclass.
setSdkFolder()	The directory the SDK will use for data storage and logs. We recommend that this folder be excluded from Auto Backup.
setTokenSigner()	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()	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()	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.
setIdentity()	The host app shares the identity of its currently authenticated user by providing an Identity object that the SDK persists through app restarts.
changePhoneId()	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.
setDiagnosticMode()	Enables a special diagnostic mode with additional SDK log messages and internal checks. Should only be used for developement and troubleshooting, not in production.
addLogListener()	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.

More information about using all these methods can be found here.

Notification Factory

The trip manager must be configured before it can be used. This is a one-time operation; the SDK remembers its configuration and, once configured, the trip manager initializes itself automatically.

You can configurate the trip manager from the React Native, but before you do it, you must create your custom Notification Factory. IMS expects SDK users to fully customize these notifications. To do this, the host app must provide its own implementation of the TripNotificationFactory interface and pass it to the library. The SDK will instantiate the class and call the appropriate method as required.

Trip recording needs to happen automatically in the background without user interaction. On Android this means it runs in a foreground service, which in turns means it requires a notification to inform the user we're using background resources.

Notifications are shown while the SDK evaluates the start of a possible trip as well as during recording.

· The notification factory must be specified or else no trips will be recorded.

· The notification factor class must not be obfuscated. You should to add a line like this to your proguard-rules file : -keep class [MyNotificationFactory].** { *; }

The Trip Notification Factory interface looks like this:

interface TripNotificationFactory {
    fun createPotentialTripNotification(context: Context): Notification
    fun createValidatedTripNotification(context: Context): Notification
}

The most basic implementation looks like this (you will want to specify the icon, title, and more):

class MyNotificationFactory : TripNotificationFactory {

  override fun createPotentialTripNotification(context: Context): Notification {

    val notificationIntent = Intent(context, MainActivity::class.java)

    return NotificationCompat.Builder(context, "silentChannel")
      .setContentIntent(PendingIntent.getActivity(context, 0, notificationIntent, 0))
      .setCategory(Notification.CATEGORY_EVENT)
      .setContentInfo("Possible trip detected, checking to see if you are driving.")
      .setContentTitle("Validating Trip")
      .build()
  }

  override fun createValidatedTripNotification(context: Context): Notification {

    val notificationIntent = Intent(context, MainActivity::class.java)

    return NotificationCompat.Builder(context, "noisyChannel"
      .setContentIntent(PendingIntent.getActivity(context, 0, notificationIntent, 0))
      .setContentText("Your trip is being recorded")
      .setContentTitle("Recording Trip")
      .build()
  }

WorkManager runtime

The SDK uses the Android WorkManager for many background operations. The SDK works with either the default or a custom WorkManager configuration.

You also need to create a custom WorkManagerInitializer so that the custom work manager is initialized before the SDK. For it use Android startup library. Since this is where you will configure the SDK and transfer your custom Notification Factory to the SDK that we described above. To pass your custom Notification Factory to the SDK, you need to usesetNotificationFactory function (see the example below). To do this, implement the following:

class MyImsSdkInitializer : Initializer<ImsSdkConfiguration?> {

  fun create(context: Context): ImsSdkConfiguration {
    //check and configure ImsSdkManager if it is necessary
    if (!ImsSdkManager.isConfigured()) {
      ImsSdkManager.setSdkConfiguration(
        context,
        Builder()
          .setApiKey("API_KEY")
          .setSdkFolder(File(context.filesDir, "ims_sdk"))
          .setTokenSigner(MyTokenSigner::class.java)
          .build()
      )
    }
    //pass your Notification Factory class to the SDK
    ImsReactNativeModule.setNotificationFactory(AppNotificationFactory::class.java)
   
    return ImsSdkManager.getConfiguration()
  }

  fun dependencies(): List<Class<out Initializer<*>?>> {
    return listOf(ImsTripManagerInitializer::class.java, WorkManagerInitializer::class.java)
  }
}

Do not forget to add following to the AndroidManifest.xml file:

<manifest 
 ...
  <application
    ...
    <provider
      android:name="androidx.startup.InitializationProvider"
      android:authorities="${applicationId}.androidx-startup"
      android:exported="false"
      tools:node="merge" >
      <meta-data
        android:name="com.example.MyImsSdkInitializer"
        android:value="androidx.startup" />
    </provider>
  </application>
</manifest>

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:

· ImsSdkManager must be configured before it is changed.

· ImsSdkManager.setSdkConfiguration called with invalid ImsSdkConfiguration.

· Cannot instantiate ImsSdkConfiguration token signer [supplied class name]. The SDK requires a custom TokenSigner class with an empty constructor. See https://sdk.ims.tech/security

NOTE: you can find additional information on the following pages: Initialize the SDK and Using the SDK.