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 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].** { *; }.
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:
There are also shortcuts for some common settings.
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.
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:
The most basic implementation looks like this (you will want to specify the icon, title, and more):
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:
Do not forget to add following to the AndroidManifest.xml file:
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.
Last updated