# MyID Android SDK

## Table of contents

- [Getting started](#getting-started)
  - [Before you begin](#11-before-you-begin)
  - [Setup MyID Android SDK](#12-setup-myid-android-sdk)
  - [Permissions](#13-permissions)
- [Usage](#usage)
  - [Methods](#11-methods)
  - [Handling callbacks](#12-handling-callbacks)
- [SDK error codes](#sdk-error-codes)
- [Google Play Automatic Integrity Protection](#google-play-automatic-integrity-protection)

## Getting started

### 1.1 Before you begin

Install or update Android Studio to its latest version.

The SDK supports API level 21 and above

Make sure that your app meets the following requirements:

- `minSdkVersion = 21`
- `targetSdkVersion = 36`
- `Kotlin = 1.8.22+`
- `android.useAndroidX = true`

``` gradle
compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}
```

### 1.2 Setup MyID Android SDK

#### Step 1: Add the Repository

First, add the Artifactory repository to the repositories block of your module's **_build.gradle_** file:

```gradle
repositories {
  maven { url "https://artifactory.myid.uz:443/artifactory/myid" }
}
```

Here’s a clean and concise documentation section based on your instructions:

---

#### Step 2: Add the Dependency

Add the required SDK dependency to your `build.gradle`:

```gradle
dependencies {
  debugImplementation("uz.myid.sdk.capture:myid-capture-sdk-debug:3.1.10")
  releaseImplementation("uz.myid.sdk.capture:myid-capture-sdk:3.1.10")
}
```

Due to the advanced validation support (in C++ code), we recommend that the integrator app performs [multi-APK split](#multi-apk-split) to optimize the app size for individual architectures.

Average size (with Proguard enabled):

| ABI         |   Size   |
|-------------|:--------:|
| armeabi-v7a | 28.7 Mb  |
| arm64-v8a   | 23.3 Mb |
| universal   | 37.2 Mb |

#

If you are using **VideoIdentification** entry mode, also include:

```gradle
dependencies {
  implementation("uz.myid.sdk.capture:myid-video-capture-sdk:3.1.10")
}
```

Average size (with Proguard enabled):

| ABI         |   Size   |
|-------------|:--------:|
| armeabi-v7a | 39.5 Mb  |
| arm64-v8a   | 35.6 Mb |
| universal   | 57.8 Mb |

**Note**: The average sizes were measured by building the minimum possible wrappers around our SDK.
Different versions of the dependencies, such as Gradle or NDK, may result in slightly different values.

#### Multi-APK split

C++ code needs to be compiled for each of the CPU architectures (known as "ABIs") present on the Android environment. Currently, the SDK supports the following ABIs:

* `armeabi-v7a`: Version 7 or higher of the ARM processor. Most recent Android phones use this
* `arm64-v8a`: 64-bit ARM processors. Found on new generation devices
* `x86`: Used by most tablets and emulators
* `x86_64`: Used by 64-bit tablets

The SDK binary contains a copy of the native `.so` file for each of these four platforms.
You can considerably reduce the size of your `.apk` by applying APK split by ABI, editing your `build.gradle` to the following:

```gradle
android {
  splits {
    abi {
        enable true
        reset()
        include 'x86', 'x86_64', 'arm64-v8a', 'armeabi-v7a'
        universalApk false
    }
  }
}
```
Read the [Android documentation](https://developer.android.com/build/configure-apk-splits) for more information.


### 1.3 Permissions

Add following lines to the **_AndroidManifest.xml_**:

``` xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
```

## Usage

### With Activity Result API

``` kotlin
class ExampleActivity : AppCompatActivity(), MyIdResultListener {

    private val client by lazy { MyIdClient() }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        startMyId()
    }

    private fun startMyId() {
        val config = MyIdConfig.Builder(sessionId = /* Your session id */)
            .withClientHash(/* Your clientHash */, /* Your clientHashId */)
            .withEnvironment(MyIdEnvironment.Production)
            .build()

        val intent = client.createIntent(activity = this, config)
        result.launch(intent)
    }

    private val result = takeMyIdResult(listener = this)
}
```

### With `onActivityResult` method

``` kotlin
class ExampleActivity : AppCompatActivity(), MyIdResultListener {

    private val client by lazy { MyIdClient() }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        startMyId()
    }
    
    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        client.handleActivityResult(resultCode, this)
    }

    private fun startMyId() {
        val config = MyIdConfig.Builder(sessionId = /* Your session id */)
            .withClientHash(/* Your clientHash */, /* Your clientHashId */)
            .withEnvironment(MyIdEnvironment.Production)
            .build()

        /*
           Start the flow. 1 should be your request code (customize as needed).
           Must be an Activity or Fragment (support library).
           This request code will be important for you on onActivityResult() to identify the MyIdResultListener.
        */
        client.startActivityForResult(this, 1, config)
    }
}
```

### 1.1 Methods

Method | Notes | Default
--- | --- | ---
`withClientHash(clientHash: String, clientHashId: String)` | Provided by MyID sales team | Mandatory, if using withEntryType(MyIdEntryType.Identification)
`withResidency(residency: MyIdResidency)` | To set a specific residency type | MyIdResidency.Resident
`withMinAge(age: Int)` | To set a specific minimum age to use MyID service | 16
`withDistance(distance: Float)` | To set a specific distance for taking photo | 0.65
`withEnvironment(environment: MyIdEnvironment)` | Environment mode (Note 1.4) | MyIdEnvironment.Production
`withEntryType(type: MyIdEntryType)` | Customizing the SDK Entry types (Note 1.5) | MyIdEntryType.Identification
`withLocale(locale: MyIdLocale)` | To set a specific locale | MyIdLocale.Uzbek
`withCameraShape(shape: MyIdCameraShape)` | To set a specific camera shape (Note 1.6) | MyIdCameraShape.Circle
`withCameraResolution(resolution: MyIdCameraResolution)` | To set a specific camera resolution | MyIdCameraResolution.Low
`withImageFormat(format: MyIdImageFormat)` | To set a specific image format | MyIdImageFormat.JPEG
`withScreenOrientation(orientation: MyIdScreenOrientation)` | To set a specific screen orientation | MyIdScreenOrientation.Portrait
`withOrganizationDetails(details: MyIdOrganizationDetails)` | Custom Organization Details | Optional
`withSoundGuides(enable: Boolean)` | To enable or disable sound guides | true
`withErrorScreen(showErrorScreen: Boolean)` | To enable or disable error screen | true
`withHuaweiAppId(appId: String)` | To set a huawei app id | Required for HMS

**Note 1.1.** `MyIdEnvironment` contains **Debug** and **Production** modes.

- **Debug** is used to sandbox.
- **Production** is used to production.

**Note 1.2.** `MyIdEntryType` contains **Identification**, **VideoIdentification** and **FaceDetection** types.

- **Identification** is used to identify the user through the MyID services.
- **VideoIdentification** is used to identify the user through the MyID services. Requires the `myid-video-capture-sdk` dependency.
- **FaceDetection** is used to detect a face and returns a picture (bitmap).

**Note 1.3.** `MyIdCameraShape` contains **[Circle](images/screen03.jpg)**
and **[Ellipse](images/screen04.jpg)** types.

**Note 1.4.** If the SDK **does not receive a passport data** and receives `residency = MyIdResidency.UserDefined`, the SDK displays the **MyID passport input screen**. If the user enters a **PINFL**, the screen will show a **checkbox** allowing the user to select **Resident** or **Non-Resident**.

### 1.2 Handling callbacks

```kotlin
val resultListener: MyIdResultListener = object : MyIdResultListener {
  override fun onSuccess(result: MyIdResult) {
    // Get face bitmap and result code

    val bitmap = result.getGraphicFieldImageByType(MyIdGraphicFieldType.FacePortrait)
    val code = result.code
  }

  override fun onUserExited() {
    // User left the SDK
  }

  override fun onError(e: MyIdException) {
    // Get error message and code:

    val message = e.message
    val code = e.code
  }
  
  override fun onEvent(event: MyIdEvent) {
    // Get event type
  }
}
```

| Attribute     |    Notes    |
| -----|-------|
| `onSuccess` | `MyIdResult` contains information about the face captures made during the flow, result code and comparison value. |
| `onUserExited` | User left the SDK flow without completing it. |
| `onError` | Some error happened. `MyIdException` contains information about the error message and code |
| `onEvent` | `MyIdEvent` contains information about the event type |

## SDK error codes

You can view the full list of SDK error codes at:

👉 [Error Codes Documentation](https://docs.myid.uz/#/ru/embedded?id=javob-kodlar-uz-result_code)

The error code in the following list may appear during the call of SDK. The list below is for your
reference.

| Code   |      Error message
|:----------:|:-------------
|  102  |  Camera access denied
|  103  |  Error while retrieving data from server or SDK
|  122  |  User banned

## Google Play Automatic Integrity Protection

The SDK is not compatible with Google Play Automatic Integrity Protection.

If this feature is on, the SDK detects the app as modified, blocks its features, and the app may crash.

To fix it:

1. Open Play Console > your app > Release > App integrity
2. Turn off Automatic protection
3. Upload a new release

We are working on support for this feature and will update this page when it is ready.