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

## Table of contents

Javokhir's avatar
Javokhir committed
5
- [Important](#important)
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
6
- [Getting started](#getting-started)
Javokhir's avatar
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
2.0.7  
Javokhir Savriev committed
10
- [Usage](#usage)
Javokhir's avatar
Javokhir committed
11
12
    - [Methods](#11-methods)
    - [Handling callbacks](#12-handling-callbacks)
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
13
14
- [SDK error codes](#sdk-error-codes)
- [Localization](#localization)
Javokhir's avatar
2.1.1    
Javokhir committed
15
- [Custom Organization Details](#custom-organization-details)
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
16

Javokhir's avatar
Javokhir committed
17
18
19
20
21
## Important

**Note:** When you update the version of MyID SDK in your application, check the version of the
libraries in [dependencies](#12-setup-myid-android-sdk) and update them too!

Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
22
23
24
25
26
27
28
29
30
31
32
## 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`
Javokhir's avatar
2.1.1    
Javokhir committed
33
- `targetSdkVersion = 33`
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
34
35
- `android.useAndroidX = true`

Javokhir's avatar
Javokhir committed
36
37
38
39
40
``` gradle
compileOptions {
  sourceCompatibility JavaVersion.VERSION_1_8
  targetCompatibility JavaVersion.VERSION_1_8
}
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
41
42
43
44
45
```

- myid-sdk-***.aar, has been provided to you, it contains SDK public interface and implementation.
  Archive name contains ever increasing release version number.

Javokhir's avatar
Javokhir committed
46
### 1.2 Setup MyID Android SDK
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
47
48

Create new project in AndroidStudio. Inside mobile application folder create new folder to store SDK
Javokhir's avatar
Javokhir committed
49
libraries (For example libs) and copy MyID SDK provided libraries.
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
50
51
52
53

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

``` gradle
Javokhir's avatar
Javokhir committed
54
implementation(files("libs/myid-sdk-2.1.2-release.aar"))
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
55
```
Javokhir's avatar
Javokhir committed
56
57
58

**Note:** You can get `myid-sdk-2.1.2-release.aar` file
from [here](app/libs/myid-sdk-2.1.2-release.aar)
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
59

Javokhir Savriev's avatar
2.0.8    
Javokhir Savriev committed
60
After synchronization, You should be able to access to SDK classes from your source code.
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
61

Javokhir's avatar
Javokhir committed
62
MyID Android SDK also requires following libraries to be added:
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
63
64

``` gradle
Javokhir's avatar
Javokhir committed
65
66
dependencies {
    implementation(files("libs/myid-sdk-2.1.2-release.aar"))
Javokhir's avatar
2.1.1    
Javokhir committed
67

Javokhir's avatar
Javokhir committed
68
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.6.4")
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
69

Javokhir's avatar
Javokhir committed
70
71
72
73
74
    implementation("androidx.core:core-ktx:1.9.0")
    implementation("androidx.appcompat:appcompat:1.5.1")
    implementation("androidx.constraintlayout:constraintlayout:2.1.4")
    implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.5.1")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.5.1")
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
75

Javokhir's avatar
Javokhir committed
76
77
78
79
    def cameraVersion = "1.2.0-rc01"
    implementation("androidx.camera:camera-camera2:$cameraVersion")
    implementation("androidx.camera:camera-lifecycle:$cameraVersion")
    implementation("androidx.camera:camera-view:$cameraVersion")
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
80

Javokhir's avatar
Javokhir committed
81
82
83
    implementation("com.google.android.gms:play-services-mlkit-face-detection:17.1.0")
    implementation("com.google.android.gms:play-services-mlkit-text-recognition:18.0.2")
    implementation("com.google.android.gms:play-services-mlkit-barcode-scanning:18.1.0")
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
84

Javokhir's avatar
Javokhir committed
85
86
87
    implementation("io.ktor:ktor-client-android:2.1.2")
    implementation("io.sentry:sentry-android:6.7.0-alpha.1")
}
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
```

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

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

Javokhir's avatar
Javokhir committed
104
    private val myIdClient = MyIdClient()
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
105
106
107
108
109
110
111

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

    private fun startMyId() {
Javohir Savriy's avatar
2.0.9    
Javohir Savriy committed
112
113
114
115
116
        val organizationDetails = OrganizationDetails(
            phoneNumber = "1234567",
            logo = R.drawable.image_logo
        )
        
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
117
118
119
120
        val myIdConfig = MyIdConfig.builder(clientId = /* Your client id */)
            .withPassportData(passportData)
            .withBirthDate(dateOfBirth)
            .withExternalId(externalId)
Javohir Savriy's avatar
2.0.9    
Javohir Savriy committed
121
            .withThreshold(threshold)
Javokhir's avatar
Javokhir committed
122
            .withBuildMode(MyIdBuildMode.PRODUCTION)
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
123
            .withEntryType(MyIdEntryType.AUTH)
Javokhir's avatar
Javokhir committed
124
125
            .withLocale(Locale("en"))
            .withCameraShape(MyIdCameraShape.CIRCLE)
Javohir Savriy's avatar
2.0.9    
Javohir Savriy committed
126
            .withOrganizationDetails(organizationDetails)
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
            .withPhoto(false)
            .build()

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

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

### 1.1 Methods

Method | Notes | Default
--- | --- | ---
`withPassportData(value: String)` | Passport serial number or PINFL data | Optional
`withBirthDate(value: String)` | Date of birth in. Format: `dd.MM.yyyy` | Optional
`withExternalId(value: String)` | 36 characters long. Should match with UUID4 regex | Optional
Javohir Savriy's avatar
Javohir Savriy committed
145
`withThreshold(value: Float)` | The value can be in the range of `0.50` - `0.99` | 0.50
Javokhir's avatar
Javokhir committed
146
147
148
149
`withBuildMode(value: MyIdBuildMode)` | Build mode | MyIdBuildMode.PRODUCTION
`withEntryType(value: MyIdEntryType)` | Customizing the SDK Entry types | MyIdEntryType.AUTH
`withLocale(value: Locale)` | To set a specific locale | Locale("uz")
`withCameraShape(value: MyIdCameraShape)` | To set a specific camera shape | MyIdCameraShape.CIRCLE
Javohir Savriy's avatar
Javohir Savriy committed
150
`withOrganizationDetails(value: OrganizationDetails)` | Custom Organization Details | Optional
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
151
152
153
154
`withPhoto(value: Boolean)` | Return SDK face bitmap | false

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

Javokhir's avatar
Javokhir committed
155
- **AUTH** is used to identify the user through the MyID services.
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
156
157
158
159
160
161
162
163
164
165
166
- **FACE** is used to detect a face and returns a picture (bitmap).

**Note 1.2.** 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.3.** `MyIdBuildMode` contains **DEBUG** and **PRODUCTION** modes.

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

Javokhir's avatar
Javokhir committed
167
168
169
170
171
172
**Note 1.4.** 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.5.** `MyIdCameraShape` contains **[CIRCLE](images/screen03.jpg)**
and **[ELLIPSE](images/screen04.jpg)** types.
Javokhir Savriev's avatar
2.0.8    
Javokhir Savriev committed
173

Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
174
175
176
### 1.2 Handling callbacks

```kotlin
Javokhir's avatar
Javokhir committed
177
val myIdResultListener: MyIdResultListener = object : MyIdResultListener {
Javokhir's avatar
2.1.1    
Javokhir committed
178
179
    override fun onSuccess(result: MyIdResult) {
        // Get face bitmap and result code
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
180

Javokhir's avatar
2.1.1    
Javokhir committed
181
182
183
184
        val bitmap = result.bitmap
        val code = result.code
        val comparison = result.comparison
    }
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
185

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

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

Javokhir's avatar
2.1.1    
Javokhir committed
193
194
195
        val message = e.message
        val code = e.code
    }
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
196
197
198
199
200
}
```

| Attribute     |    Notes    |
| -----|-------|
Javohir Savriy's avatar
Javohir Savriy committed
201
| `onSuccess` | `MyIdResult` contains information about the face captures made during the flow, result code and comparison value. |
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
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
| `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  |  Обнаружены затемненные очки
Javokhir Savriev's avatar
2.0.8    
Javokhir Savriev committed
235
|  25  |  Тип фотографии не поддерживается
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
236
|  26  |  Глаза закрыты либо не видны
Javokhir Savriev's avatar
2.0.8    
Javokhir Savriev committed
237
|  101  |  Непредвиденная ошибка
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
238
239
|  102  |  Доступ к камере запрещен
|  103  |  Ошибка при получении данных с сервера
Javokhir Savriev's avatar
2.0.8    
Javokhir Savriev committed
240
|  120  |  Размытое фото обнаружено в SDK
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
241
242
243

## Localization

Javokhir's avatar
Javokhir committed
244
The MyID Android SDK supports translations for the following languages:
Javokhir Savriev's avatar
2.0.7  
Javokhir Savriev committed
245
246
247
248
249

- Uzbek      (uz) 🇺🇿
- English    (en) 🇬🇧
- Russian    (ru) 🇷🇺

Javokhir's avatar
Javokhir committed
250
By default, the Uzbek language is used. However, you can also call the `withLocale(Locale)`
Javokhir's avatar
2.1.1    
Javokhir committed
251
method of the `MyIdConfig.Builder` configuration to set the language.
Javohir Savriy's avatar
Javohir Savriy committed
252
253
254

## Custom Organization Details

Javokhir's avatar
Javokhir committed
255
256
257
258
259
260
261
262
263
264
You can customize the SDK, for it to match your organization's brand book, by
providing `OrganizationDetails` object to `withOrganizationDetails` method. The object allows you to
customize following fields:

- *phoneNumber* - by default 712022202, which is MyID's call center. If you would like the customer
  to call your own call center, you can display your own phone number on the error screen, by
  providing it in this field ([sample](images/screen01.jpg)).
- *logo* - the drawable asset, that will be displayed on the input screen. If you would like to
  display your own logo on the top of the screen, this is the place to provide it. Make sure it fits
  the imageView element, which has the *240x60* size.