## Minimum requirements
Before getting started, check that your development environment meets the following requirements:

- Target SDK 34
- Minimum SDK 21
- Kotlin version 1.8.10 or later
- Gradle version 8.0 or later

#### Upgrading to Android DocV SDK v5.4.0 or later
This version is required to use **Kotlin Version 2.1.0 or later**. This is required to support the latest language features and library dependencies utilized in this version.

When upgrading to the **Android DocV v5.4.0 SDK or later**, you must also update the **Digital Intelligence SDK** to at least **v4.8.0**.

#### Using the Digital Intelligence SDK independently
If your application integrates the Digital Intelligence SDK **outside of DocV** (for example, for standalone device capture or validation), you must install the Digital Intelligence SDK **alongside DocV** to avoid runtime errors.

## Installation
Follow the steps below to set up the Android SDK.

1. Add the Socure Maven URL to the root/project level in `build.gradle`:

```groovy
   allprojects {
       repositories {
           ...
           maven {
               url "https://sdk.socure.com/"
           }
       }
   }
   ```

2. Add the SDK dependency to the app's gradle file, make sure to set the version number to the latest one:

```groovy
   implementation 'com.socure.devicerisk.sdk:socure-devicerisk:${sigmaReleaseDetails.android.version}'
   ```

3. Specify `android:allowBackup="true"` in your app's `AndroidManifest.xml` application attributes. This will improve persistence of your `sessionToken` when your app gets reinstalled for clients who have enabled backup in their device settings.

### Proguard Rules
If minify is enabled in Gradle `minifyEnabled true` add the following in your proguard rules:

```undefined
-keep class com.socure.idplus.** { *; }
```

## Configuration and usage
The Digital Intelligence Android SDK's main class is `SigmaDevice`. At a high level the SDK provides the following methods to collect data to send it to the Socure backend:

- `initializeSDK()`
- `processDevice()`

### `initializeSDK()`
Prior to interacting with the Digital Intelligence Android SDK, it must be initialized with `sdkKey` obtained from the **[Developer Workbench > SDK Keys](https://help.socure.com/riskos/docs/integration-guide-authentication#/)** page in RiskOS™.

The `initializeSDK()` function configures the SDK. It requires the Android `context`, `sdkKey`, `sigmaDeviceOptions` and a `sigmaDeviceCallback`. It should preferably be called from the App's Application class at the time of initialization:

```kotlin
initializeSDK(
  context: Context,
  sdkKey: String,
  sigmaDeviceOptions: SigmaDeviceOptions,
  sigmaDeviceCallback: SigmaDeviceCallback
)
```

#### `SigmaDeviceOptions`
These options can be passed into the `initializeSDK()` method to customize the SDK operation. It is represented as below:

```kotlin
data class SigmaDeviceOptions(
  val omitLocationData: Boolean = false,
  val advertisingID: String? = null,
  val useSocureGov: Boolean = false,
  val configBaseUrl: String? = null,
  var customerSessionId: String?)
```

- `omitLocationData`: A boolean flag used to omit the location data from being sent as part of data collection. By default, it is set to `false`. When set to `true,` the location data will not be included during data collection regardless of the location permission given by the user.
- `advertisingID`: An optional string value that, when passed, will allow the advertising ID information to be sent as a part of data collection. Defaults to `null`.
- `useSocureGov`: A boolean flag used to configure the DeviceRisk SDK to communicate with the SocureGov backend. Defaults to `false`. This only applies to customers provisioned in the SocureGov environment. This flag is ignored if a `configBaseUrl` is provided.
- `configBaseUrl`: An optional string that configures the SDK to use a custom base URL for retrieving SDK configuration information.
- `customerSessionId`: An optional value that allows a customer provided identifier to be used in place of the SDK generated session token when calling Socure services.

#### `SigmaDeviceCallback`
`SigmaDeviceCallback` provides information about the status of the initialization call. The `initializeSDK()` call sets up data collection and returns the created `sessionToken` using the `onSessionCreated()` callback. The `sessionToken` can then be used on the respective device endpoints to fetch the data associated with the Session. Once retrieved, this `sessionToken` should be recorded by your application for use in API requests associated with this transaction. The `sessionToken` will be passed in an API call in the `di_session_token` field.

```kotlin
fun onSessionCreated(sessionToken: String) {}
```

### `getSessionToken()`
This API lets the caller fetch the latest `sessionToken` generated by the SDK(including the one generated by `initializeSDK()`). The returned `sessionToken` can then be forwarded to the device endpoints to fetch the data associated with the Session:

```kotlin
fun getSessionToken(sessionTokenCallback: SessionTokenCallback)
```

Once retrieved, this `sessionToken` should be recorded by your application for use in API requests associated with this transaction. The `sessionToken` will be passed in an API call in the `di_session_token` field.

#### `SessionTokenCallback`
`SessionTokenCallback` returns the latest `sessionToken` seen by the SDK. Here we return the `sessionToken` using the `onComplete()` callback. The `sessionToken` can then be used on the respective device endpoints to fetch the data associated with the Session. Once retrieved, this `sessionToken` should be recorded by your application for use in API requests associated with this transaction. The `sessionToken` will be passed in an API call in the `di_session_token` field.

```kotlin
fun onComplete(sessionToken: String) {}
```

### Error Handling
Both the `SigmaDeviceCallback` and `SessionTokenCallback` provide an `onError()` callback to let the user know when the SDK encounters an error. The `SigmaDeviceError` denotes the type of the error. We also provide an additional `errorMessage` string for a more descriptive message around the error.

```kotlin
fun onError(errorType: SigmaDeviceError, errorMessage: String?)
```

Below are the types of errors returned by the SDK:

```kotlin
SigmaDeviceError:
   NetworkConnectionError,
   DataUploadError,
   DataFetchError,
   UnknownError,
   ContextFetchError,
   SdkNotInitializedError,
   SdkPausedError
```

### Controlling Data Collection
By default, the SDK will begin collecting data automatically. This includes data about the device and the way the user is interacting with the application. This data will be tracked as long as the application is in the foreground. Data collection is paused automatically when the application is backgrounded and automatically resumed when foregrounded.

In the event that further control over data collection is needed, two methods are supplied by the SDK:

- `SigmaDevice.pauseDataCollection()` \- Will pause ongoing user behavior and interaction data collection. Data collection will not resume until `SigmaDevice.resumeDataCollection()` is called.
- `SigmaDevice.resumeDataCollection()` \- Will resume data collection if collection was paused.

## Advanced Usage
### `processDevice()`
The `initializeSDK()` method automatically collects the data when initialized. Typically, the data collected by `initializeSDK()` should be sufficient for most use cases. In cases where you need to explicitly invoke a data collection step, you can make use of `processDevice()`. Here we provide a `SigmaDeviceContext` to define the flow or screen within which the call occurs.

```kotlin
fun processDevice(sigmaDeviceContext: SigmaDeviceContext, sessionTokenCallback: SessionTokenCallback)
```

#### `SigmaDeviceContext`
The following context values can be provided when calling `processDevice()`:

```kotlin
SigmaDeviceContext:
   Default,
   Home,
   SignUp,
   Login,
   Password,
   Checkout,
   Profile,
   Transaction,
   Other("Custom Value")
```

Note the `initializeSDK()` collects data with the `SigmaDeviceContext` set to `Default`.

## Silent Network Authentication
The Digital Intelligence Android SDK provides the `performSilentNetworkAuth(mobileNumber, silentNetworkAuthCallback)` method to perform Silent Network Authentication using SIM-based verification. This allows you to verify device possession of a specified mobile number without requiring user interaction.

Silent Network Authentication is performed asynchronously. The result is not returned directly to the caller, but is made available for use within RiskOS™ decisioning workflows.

**Requirements:**
- The device must have an active SIM card and cellular data enabled.
- Devices on Wi-Fi will be automatically switched to cellular for authentication.
- Devices without cellular connectivity or with no SIM will not complete authentication, but this status is still reported for workflow decisioning.
- Your account must be provisioned for the `SilentNetworkAuth` feature.
- The `android.permission.CHANGE_NETWORK_STATE` permission must be added in your app's manifest to allow the SDK to switch network states.

**Usage Example:**

```kotlin
SigmaDevice.performSilentNetworkAuth(
    mobileNumber = "+12345678901",
    silentNetworkAuthCallback = object : SilentNetworkAuthCallback {
        override fun onSuccess() {
            println("Silent Network Authentication initiated")
        }
        override fun onError(error: SilentNetworkAuthError, errorMessage: String?) {
            println("An error occurred: $errorMessage")
        }
    }
)
```

The `mobileNumber` parameter should be provided in E.164 format (for example, "+12345678901").

> 📘
> **Note**:
> The Silent Network Authentication process is not complete until the `SilentNetworkAuthCallback` reports completion through `onSuccess()` or `onError(...)`.

> 📘
> **Note**:
> The result of the authentication is not returned directly. It is available for use in RiskOS™ workflows.

Updated 3 days ago