README.md 9.66 KB
Newer Older
Javokhir Savriev's avatar
Javokhir Savriev committed
1
2
3
4
# MyID Android SDK

## Table of contents

Javohir Savriy's avatar
Javohir Savriy committed
5
- [Changelog](CHANGELOG.md)
Javokhir Savriev's avatar
Javokhir Savriev committed
6
- [Getting started](#getting-started)
Javokhir's avatar
2.2.2    
Javokhir committed
7
8
9
  - [Before you begin](#11-before-you-begin)
  - [Setup MyID Android SDK](#12-setup-myid-android-sdk)
  - [Permissions](#13-permissions)
Javokhir Savriev's avatar
Javokhir Savriev committed
10
- [Usage](#usage)
Javokhir's avatar
2.2.2    
Javokhir committed
11
12
  - [Methods](#11-methods)
  - [Handling callbacks](#12-handling-callbacks)
Javokhir Savriev's avatar
Javokhir Savriev committed
13
- [SDK error codes](#sdk-error-codes)
Javohir Savriy's avatar
2.1.6    
Javohir Savriy committed
14
- [UI customization](CUSTOMIZATION.md)
Javokhir Savriev's avatar
Javokhir Savriev committed
15
16
17
18
19
20
21
22
23
24
25
26

## 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`
Javohir Savriy's avatar
Javohir Savriy committed
27
- `targetSdkVersion = 34`
Javohir Savriy's avatar
Javohir Savriy committed
28
- `Kotlin = 1.8.10+`
Javokhir Savriev's avatar
Javokhir Savriev committed
29
30
31
32
33
34
35
36
37
38
39
40
41
- `android.useAndroidX = true`

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

### 1.2 Setup MyID Android SDK

Add reference to library to module **_build.gradle_**:

Javohir Savriy's avatar
Javohir Savriy committed
42
43
44
45
```gradle
repositories {
  maven { url "https://artifactory.aigroup.uz:443/artifactory/myid" }
}
Javokhir Savriev's avatar
Javokhir Savriev committed
46
47

dependencies {
Javohir Savriy's avatar
Javohir Savriy committed
48
  implementation("uz.myid.sdk.capture:myid-capture-sdk:2.3.1")
Javokhir Savriev's avatar
Javokhir Savriev committed
49
50
51
}
```

Javohir Savriy's avatar
Javohir Savriy committed
52
53
After synchronization, You should be able to access to SDK classes from your source code.

Javokhir Savriev's avatar
Javokhir Savriev committed
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
### 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 {

Javokhir's avatar
2.2.7    
Javokhir committed
70
    private val client = MyIdClient()
Javokhir Savriev's avatar
Javokhir Savriev committed
71
72
73
74
75
76
77

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

    private fun startMyId() {
Javokhir's avatar
2.2.7    
Javokhir committed
78
        val config = MyIdConfig.builder(clientId = /* Your client id */)
Javokhir's avatar
2.2.2    
Javokhir committed
79
            .withClientHash(/* Your clientHash */, /* Your clientHashId */)
Javokhir Savriev's avatar
Javokhir Savriev committed
80
81
82
83
84
            .withPassportData(passportData)
            .withBirthDate(dateOfBirth)
            .withBuildMode(MyIdBuildMode.PRODUCTION)
            .build()

Javokhir's avatar
2.2.7    
Javokhir committed
85
        val intent = client.createIntent(activity = this, config)
Javokhir Savriev's avatar
Javokhir Savriev committed
86
87
88
89
90
91
92
93
94
95
96
97
        result.launch(intent)
    }

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

### With `onActivityResult` method

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

Javokhir's avatar
2.2.7    
Javokhir committed
98
    private val client = MyIdClient()
Javokhir Savriev's avatar
Javokhir Savriev committed
99
100
101
102
103
104
105
106

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        startMyId()
    }
    
    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
Javokhir's avatar
2.2.7    
Javokhir committed
107
        client.handleActivityResult(resultCode, this)
Javokhir Savriev's avatar
Javokhir Savriev committed
108
109
110
    }

    private fun startMyId() {
Javokhir's avatar
2.2.7    
Javokhir committed
111
        val config = MyIdConfig.builder(clientId = /* Your client id */)
Javokhir's avatar
2.2.2    
Javokhir committed
112
            .withClientHash(/* Your clientHash */, /* Your clientHashId */)
Javokhir Savriev's avatar
Javokhir Savriev committed
113
114
115
116
117
118
119
120
121
122
            .withPassportData(passportData)
            .withBirthDate(dateOfBirth)
            .withBuildMode(MyIdBuildMode.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.
        */
Javokhir's avatar
2.2.7    
Javokhir committed
123
        client.startActivityForResult(this, 1, config)
Javokhir Savriev's avatar
Javokhir Savriev committed
124
125
126
127
128
129
130
131
    }
}
```

### 1.1 Methods

Method | Notes | Default
--- | --- | ---
Javokhir's avatar
2.2.2    
Javokhir committed
132
`withClientHash(clientHash: String, clientHashId: String)` | Provided by MyID sales team | Mandatory, if using withEntryType(MyIdEntryType.AUTH)
Javokhir Savriev's avatar
Javokhir Savriev committed
133
`withPassportData(value: String)` | Passport serial number or PINFL data | Optional
Javokhir's avatar
2.2.7    
Javokhir committed
134
135
136
`withBirthDate(value: String)` | Date of birth. Format: `dd.MM.yyyy` | Optional
`withMinAge(value: Int)` | To set a specific minimum age to use MyID service | 16
`withSdkHash(value: String)` | 32 characters long string (Note 1.2) | Optional
Javohir Savriy's avatar
Javohir Savriy committed
137
`withExternalId(value: String)` | 36 characters long. Should match with UUID4 regex (Note 1.3) | Optional
138
`withThreshold(value: Float)` | The value can be in the range of `0.55` - `0.99` | 0.55
Javokhir's avatar
2.2.7    
Javokhir committed
139
140
`withBuildMode(value: MyIdBuildMode)` | Build mode (Note 1.4) | MyIdBuildMode.PRODUCTION
`withEntryType(value: MyIdEntryType)` | Customizing the SDK Entry types (Note 1.5) | MyIdEntryType.AUTH
Javokhir Savriev's avatar
Javokhir Savriev committed
141
142
`withResidency(value: MyIdResidentType)` | To set a specific resident type | MyIdResidentType.RESIDENT
`withLocale(value: Locale)` | To set a specific locale | Locale("uz")
Javokhir's avatar
2.2.7    
Javokhir committed
143
`withCameraShape(value: MyIdCameraShape)` | To set a specific camera shape (Note 1.6) | MyIdCameraShape.CIRCLE
Javohir Savriy's avatar
Javohir Savriy committed
144
`withResolution(value: MyIdResolution)` | To set a specific camera resolution | MyIdResolution.RESOLUTION_480
Javokhir's avatar
2.2.7    
Javokhir committed
145
`withScreenOrientation(value: MyIdScreenOrientation)` | To set a specific screen orientation | MyIdScreenOrientation.FULL
Javokhir Savriev's avatar
Javokhir Savriev committed
146
`withImageFormat(value: MyIdImageFormat)` | To set a specific image format | MyIdImageFormat.PNG
Javohir Savriy's avatar
2.1.6    
Javohir Savriy committed
147
`withOrganizationDetails(value: MyIdOrganizationDetails)` | Custom Organization Details | Optional
Javokhir Savriev's avatar
Javokhir Savriev committed
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175

**Note 1.1.** You can customize the screen for entering passport data and date of birth in your
application, in which case you can pass these parameters during initialization to the SDK, otherwise
the SDK requires the input of passport data and date of birth for user identification.

**Note 1.2.** If the `sdk_hash` is empty, blank or string with length other than 32 has been
provided, we will continue showing the credentials screen.

**Note 1.3.** If the `externalId` is not empty, has a length of 36 characters and corresponds to the
regular expression UUID4, we will display a [recommendation](images/screen01.jpg) screen in case the
sdk detects a blurry photo.

**Note 1.4.** `MyIdBuildMode` contains **DEBUG** and **PRODUCTION** modes.

- **DEBUG** is used to sandbox.
- **PRODUCTION** is used to production.

**Note 1.5.** `MyIdEntryType` contains **AUTH** and **FACE** types.

- **AUTH** is used to identify the user through the MyID services.
- **FACE** is used to detect a face and returns a picture (bitmap).

**Note 1.6.** `MyIdCameraShape` contains **[CIRCLE](images/screen03.jpg)**
and **[ELLIPSE](images/screen04.jpg)** types.

### 1.2 Handling callbacks

```kotlin
Javokhir's avatar
2.2.7    
Javokhir committed
176
val resultListener: MyIdResultListener = object : MyIdResultListener {
Javokhir's avatar
2.2.2    
Javokhir committed
177
178
  override fun onSuccess(result: MyIdResult) {
    // Get face bitmap and result code
Javokhir Savriev's avatar
Javokhir Savriev committed
179

Javokhir's avatar
Javokhir committed
180
    val bitmap = result.getGraphicFieldImageByType(MyIdGraphicFieldType.FACE_PORTRAIT)
Javokhir's avatar
2.2.2    
Javokhir committed
181
182
183
    val code = result.code
    val comparison = result.comparison
  }
Javokhir Savriev's avatar
Javokhir Savriev committed
184

Javokhir's avatar
2.2.2    
Javokhir committed
185
186
187
  override fun onUserExited() {
    // User left the SDK
  }
Javokhir Savriev's avatar
Javokhir Savriev committed
188

Javokhir's avatar
2.2.2    
Javokhir committed
189
190
  override fun onError(e: MyIdException) {
    // Get error message and code:
Javokhir Savriev's avatar
Javokhir Savriev committed
191

Javokhir's avatar
2.2.2    
Javokhir committed
192
193
194
    val message = e.message
    val code = e.code
  }
Javokhir Savriev's avatar
Javokhir Savriev committed
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
}
```

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

## SDK error codes

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

| Code |      Error message
|:----:|:-------------
|  2   |  Паспортные данные введены неправильно
|  3   |  Не удалось подтвердить жизненность
|  4   |  Не удалось распознать
|  5   |  Внешний сервис недоступен или работает некорректно
|  6   |  Запрашиваемый пользовател скончался
|  7   |  Фото с ресурсов не получено
|  8   |  Внутренняя ошибка MyID
|  9   |  Срок выполнения задачи истек
|  10  |  Срок ожидания задачи в очереди истек
|  11  |  Сервис MyID не может обработать запрос. Попробуйте повторить позже
|  12  |  Сервис MyID не может обработать запрос. Попробуйте повторить позже
|  13  |  Сервис MyID не может обработать запрос. Попробуйте повторить позже
|  14  |  Не удалось подтвердить жизненность. Некорректная фотография
|  15  |  Сервис MyID не может обработать запрос. Попробуйте повторить позже
|  16  |  Сервис MyID не может обработать запрос. Попробуйте повторить позже
|  17  |  Не удалось распознать. Некорректная фотография
|  18  |  Сервис проверки жизненности не может обработать запрос
|  19  |  Сервис распознования не может обработать запрос
|  20  |  Размытая фотография
|  21  |  Лицо не полностью изображено
|  22  |  Обнаружено несколько лиц
|  23  |  Представленное изображение в градациях серого, требуется цветное изображение
|  24  |  Обнаружены затемненные очки
|  25  |  Тип фотографии не поддерживается
|  26  |  Глаза закрыты либо не видны
|  27  |  Обнаружено вращение головы
|  28  |  Не удалось обнаружить все ориентиры
| 101  |  Непредвиденная ошибка
| 102  |  Доступ к камере запрещен
| 103  |  Ошибка при получении данных с сервера
Javohir Savriy's avatar
Javohir Savriy committed
241
| 120  |  Размытое фото обнаружено в SDK