# 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:

* **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 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.

### Getting and setting the SDK configuration

SDK configuration is accessed through the global `ImsSdk` object.

Sample code for configuring the SDK:

```kotlin
if (!ImsSdkManager.isConfigured) {
    ImsSdkManager.setSdkConfiguration( context,
        ImsSdkManager.Builder()
            .setSdkFolder(File(context.filesDir, "ims_sdk"))
            .setTokenSigner(MyTokenSigner::class.java)
            .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.

<table><thead><tr><th width="265">Set, Get</th><th>Description</th></tr></thead><tbody><tr><td><code>setSdkFolder()</code><br><code>rootFolder</code></td><td>The directory the SDK will use for data storage and logs. We recommend that this folder be excluded from Auto Backup.</td></tr><tr><td><code>setTokenSigner()</code><br><code>tokenSigner</code></td><td>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.</td></tr><tr><td><code>setUploadWiFiOnly()</code><br><code>isUploadWiFiOnly</code></td><td>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.</td></tr><tr><td><code>setLogUploadInterval()</code><br><code>logUploadInterval</code></td><td>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.</td></tr><tr><td><code>setHeartbeatInterval()</code><br><code>heartbeatInterval</code></td><td>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.</td></tr><tr><td><code>changePhoneId()</code><br><code>phoneId</code></td><td>The SDK generates a unique identifier for each phone. This is used internally for trip recording and other functions.<br>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 <code>ImsSdk.changePhoneId()</code> to generate a new identifier.</td></tr></tbody></table>

## Utility functions

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

**User Identity**

```
// Suspended Method (Must be called from a coroutine)
ImsSdkManager.setIdentity(context: Context, identity: Identity): Result<Unit>
```

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. Any SDK API call made after invoking this method will fail.

**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.

## 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.\
  See [https://sdk.ims.tech/getting-started/android/initialize-the-sdk](/readme/android/initialize-the-sdk.md)
* ImsSdkManager.setSdkConfiguration called with invalid ImsSdkConfiguration.\
  See [https://sdk.ims.tech/getting-started/android/initialize-the-sdk](/readme/android/initialize-the-sdk.md)
* 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://sdk.ims.tech/readme/android/initialize-the-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.