# Identity Verification iOS SDK

`Version 0.1.0`

You can use the Identity Verification iOS SDK to redirect applicants to attempts in your iOS mobile app.

> **Information**
>
> To enable the SDK for your Identity Verification [configuration ID](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities/using-the-api.md#Configuration) supports the SDK, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

---

## Before you start

You must have integrated the [Identity Verification](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities.md) solution.

### Minimum requirements

The following minimum versions apply:
- iOS 15
- Swift 5.5
- Xcode 16

---

## How it works

Follow these steps:

1. Install the SDK and add your logo.
2. Add the camera permissions request.
3. Customize and localize the user interface (UI).
4. Initialize the SDK.

---

## Install the SDK

When you receive the Identify Verification iOS SDK ZIP file from your account manager, install the SDK using Swift Package Manager:

1. In your Xcode project, go to _File_ > _Add packages_.
2. Enter the following URL: `https://github.com/checkout/checkout-ios-identity-verification`.
3. Add `CheckoutIDV` to your app target.

Alternatively, you can add the dependencies in your `Package.swift`:

```swift
.dependencies = [
    .package(url: "https://github.com/checkout/checkout-ios-identity-verification", from: "0.1.0")
]

.targets = [
    .target(
        name: "<your-app>",
        dependencies: [
            .product(name: "CheckoutIDV", package: "checkout-ios-identity-verification")
        ]
    )
]
```

> **Information**
>
> Checkout.com sends you a new .zip file when we release updates to the SDK.

### Add your logo

In your Xcode project's assets library, add your business's logo as a PNG file.

> **Information**
>
> For information on providing a logo for dark mode, see Apple Developer – [Providing images for different appearances](https://developer.apple.com/documentation/uikit/providing-images-for-different-appearances).

---

## Add camera permissions request

In your app's `Info.plist` file, add a message telling applicants that your app is requesting permission to access their device camera to complete the verification.

```xml
<key>NSCameraUsageDescription</key>
<string>We need access to your camera to verify your identity.</string>
```

> **Information**
>
> For more information, see Apple Developer – [NSCameraUsageDescription](https://developer.apple.com/documentation/BundleResources/Information-Property-List/NSCameraUsageDescription).

### Manual camera permission

If the applicant first denies camera permission and then manually enables it in their iOS Settings, the operating system terminates and then restarts your app to apply the change.

You are responsible for providing a smooth user experience when handling this scenario.
For example, by restoring the app's state and re-initiating the verification on relaunch.

---

## Customize the user interface

### UI theme

You can use the `IDVTheme` struct to customize the following elements of the verification UI:

- Button corner radius
- Colors
- Fonts
- Logo

```swift
import CheckoutIDV

let theme = IDVTheme(
   colors: ...,
   typography: ...,
   buttonCornerRadius: ...,
   logoImage: ...
)
```

### Business name

You can use the `IDVConfiguration` struct to customize the commercial name for your business that appears in the UI:

```swift
let configuration = IDVConfiguration(commercialName: "<your-business-name>", theme: theme)
```

### Localization

The UI supports the following languages:

- Chinese (simplified)
- Dutch
- English (UK)
- English (US)
- Estonian
- Finnish
- French
- German
- Italian
- Japanese
- Korean
- Latvian
- Polish
- Portuguese
- Romanian
- Russian
- Slovak
- Spanish
- Swedish

---

## Initialize the SDK

1. Call the [Create an attempt](https://www.checkout.com/docs/business-operations/manage-identities/verify-identities.md#Create_an_attempt) endpoint from your back end, which returns the following:

- The attempt URL, which is valid for 15 minutes, in the `verification_url` field
- The `client_secret`, which is valid for 48 hours, to authorize the verification

2. With the SDK, create an `IdentityVerification` instance with your configuration and theme.

> **Information**
>
> The lifecycle of the `IdentityVerification` must outlive the `IdentityVerificationView`.
> We recommend having a long-living view, or having your preferred dependency container own it.

3. Create the `IdentityVerificationView`, which takes the client `IdentityVerification` as a parameter.
When the view is displayed, start the client by calling the `start` method and pass the attempt URL and the client secret:

```swift
import SwiftUI
import CheckoutIDV

struct ContentView: View {
    @StateObject private var idvClient = IdentityVerification(configuration: .init(commercialName: "<Your-business-name>", theme: .default))
    var body: some View {
        IdentityVerificationView(idv: idvClient)
        .task {
            let returnReason = await idvClient.start(clientSecret: "<Your-client-secret>", verificationURL: "<Attempt-url>")
            // Handle the return reason
            switch returnReason {
                case .success:
                    print("success")
                default:
                    print("error")
            }
        }
    }
}
```

The method returns the verification result as a `ReturnReason`.

To retry a verification, call the `start` method again.

---

## Handle the verification result

When the verification is completed and the result is available, catch the `ReturnReason` enum.

| Enum | Description |
| --- | --- |
| `success` | The verification was completed successfully. |
| `refusal` | The applicant selected a button to refuse to perform the verification.<br><br>This can have the value `refusal`. |
| `retryRequired` | The applicant needs to retry the verification. <br><br>Create a new attempt.<br><br>This can have the following values:<br><br>- `connectionIssue` – The network connection was weak or the video quality was poor.<br>- `error` – An unexpected technical error occurred during the attempt.<br>- `focusLost` – The applicant navigated away from your app during the attempt.<br>- `noDocument` – The applicant indicated that they did not have their identity document available to complete the verification.<br>- `verifyLater` – The applicant selected a button to complete the verification at a later time. |

> **Information**
>
> Each `ReturnReason` value returns a response code that provides more information about the reason.
> See [Identities response codes](https://www.checkout.com/docs/developer-resources/codes/identities-codes.md#Response_codes).