# MyID iOS SDK

## Table of contents

- [Changelog](CHANGELOG.md)
- [Getting started](#getting-started)
  - [Before you begin](#11-before-you-begin)
  - [Add the SDK dependency](#12-add-the-sdk-dependency)
  - [Permissions](#13-permissions)
- [Usage](#usage)
  - [Options](#21-options)
  - [Handling callbacks](#22-handling-callbacks)
- [SDK error codes](#sdk-error-codes)
- [UI customization](CUSTOMIZATION.md)

## Getting started

### 1.1 Before you begin

Install or update Xcode to its latest version.
The SDK supports iOS 12+. The SDK has been built on Xcode 14.1 using Swift 5.8

### 1.2 Add the SDK dependency

#### Using Swift Package Manager

The SDK is available with Swift Package Manager, and you can include it in your project by adding the following package
repository URL:

##### Swift

```swift
dependencies: [
    .package(url: "https://gitlab.myid.uz/myid-public-code/myid-ios-sdk.git", .branch("master"))
]
```

#### Using Cocoapods

The SDK is available on Cocoapods and you can include it in your projects by adding the following to your Podfile:

```ruby
pod 'MyIdSDK', '~> 2.3.4'
```

Run `pod install` to get the SDK.

#### [Manual installation](MANUAL_INSTALLATION.md)

### 1.3 Permissions

The SDK uses the device camera. You're required to have the following keys in your application's `Info.plist` file:
*  `NSCameraUsageDescription`

```xml
<key>NSCameraUsageDescription</key>
<string>Required for document and facial capture</string>
```
**Note**: All keys will be required for app submission.

## Usage
``` swift
import UIKit
import MyIdSDK

class ViewController : UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
    }
    
    private func startMyId() {
        let config = MyIdConfig()
        config.clientId = /* Your Client ID */
        config.clientHash = /* Your Client Hash */
        config.clientHashId = /* Your Client Hash ID */
        config.passportData = passportData
        config.dateOfBirth = dateOfBirth
        config.buildMode = MyIdBuildMode.PRODUCTION
        
        MyIdClient.start(withConfig: config, withDelegate: self)
    }
}

extension ViewController: MyIdClientDelegate {
    
    func onSuccess(result: MyIdResult) {
        if let code = result.code {
            print(code)
        }

        if let comparison = result.comparisonValue {
            print(comparison)
        }
        
        if let image = result.image {
            print(img)
        }
    }
    
    func onError(exception: MyIdException) {
        print(exception.code)
        print(exception.message)
    }

    func onUserExited() {
        print("User exited")
    }
}
```
### 2.1 Options

Option | Notes | Default
--- | --- | ---
`clientId` | Client ID | Provided by MyID sales team. Mandatory, if using entryType = MyIdEntryType.AUTH
`clientHash` | Client Hash | Provided by MyID sales team. Mandatory, if using entryType = MyIdEntryType.AUTH
`clientHashId` | Client Hash ID | Provided by MyID sales team. Mandatory, if using entryType = MyIdEntryType.AUTH
`passportData` | Passport serial number or PINFL data | Optional
`dateOfBirth` | Date of birth in. Format: `dd.MM.yyyy` | Optional
`minAge` | To set a specific minimum age to use MyID service | 16
`sdkHash` | 32 characters long string (Note 1.2) | Optional
`externalId` | 36 characters long. Should match with UUID4 regex (Note 1.3) | Optional
`threshold` | The value can be in the range of `0.55` - `0.99` | 0.55
`buildMode` | Build mode (Note 1.4) | MyIdBuildMode.PRODUCTION
`entryType` | Customizing the SDK Entry types (Note 1.5) | MyIdEntryType.AUTH
`residency` | To set a specific resident type | MyIdResidentType.RESIDENT
`locale` |  To set a specific locale | MyIdLocale.UZ
`cameraShape` | To set a specific camera shape (Note 1.6) | MyIdCameraShape.CIRCLE
`resolution` | To set a specific camera resolution | MyIdResolution.RESOLUTION_480
`withPhoto` | Return SDK face image | false

**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 `sdkHash` 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 not display a [recommendation](images/screen01.jpg) screen. If 5 unsuccessful identification attempts in MyID within one hour and the `externalId` is not empty, SDK returns to the parent app error message and TTL as `message` in `MyIdException`.

TTL error example:

```json
{"ttl": 362}
```

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

### 2.2 MyIdClientDelegate

```swift
extension ViewController: MyIdClientDelegate {
    
    func onSuccess(result: MyIdResult) {
        // Get face bitmap and result code

        if let code = result.code {
            print(code)
        }

        if let comparison = result.comparisonValue {
            print(comparison)
        }
        
        if let image = result.image {
            print(img)
        }
    }
    
    func onError(exception: MyIdException) {
        // Get error message and code

        print(exception.code)
        print(exception.message)
    }

    func onUserExited() {
        // User left the SDK
    }
}
```

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

## 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  |  Глаза закрыты либо не видны
|  101  |  Непредвиденная ошибка
|  102  |  Доступ к камере запрещен
|  103  |  Ошибка при получении данных с сервера
|  120  |  Размытое фото обнаружено в SDK