> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vlenseg.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vlenseg.com/_mcp/server.

# iOS SDK

The VLens iOS SDK embeds the full identity verification experience — national ID scanning, liveness detection, and face matching — directly into your iOS app. It supports both SwiftUI and UIKit and uses ARKit face tracking for liveness.

#### [GitHub](https://github.com/Vlens2021/vlens-ios-sdk/releases/tag/1.4.4)

vlens-ios-sdk · v1.4.4

#### iOS

iOS 15.0+, Swift 5.5+

#### Xcode

Xcode 13.0+, TrueDepth camera required

Liveness detection requires a TrueDepth camera (iPhone X and later, excluding SE models). Devices without TrueDepth will fail unless `allowNonTrueDepthFallback` is enabled, in which case auto-capture fires every 2 seconds as a fallback.

***

## Installation

### Swift Package Manager (recommended)

1. In Xcode, go to **File → Add Package Dependencies...**
2. Enter the repository URL: `https://github.com/Vlens2021/vlens-ios-sdk`
3. Select version **1.4.4** (or latest) and click **Add Package**

***

## Required permissions

Add the following key to your `Info.plist`:

```xml
<key>NSCameraUsageDescription</key>
<string>Camera is required for identity verification</string>
```

***

## Quick start — SwiftUI

```swift
import SwiftUI
import VLensLib

struct ContentView: View {
    @State private var showVLens = false
    @State private var accessToken = ""

    var body: some View {
        Button("Start Verification") {
            showVLens = true
        }
        .vlensVerification(
            isPresented: $showVLens,
            transactionId: UUID().uuidString,
            apiKey: "YOUR_API_KEY",
            secretKey: "",
            tenancyName: "YOUR_TENANCY_NAME",
            accessToken: accessToken,
            onSuccess: { txnId, userData in
                print("Verified: \(userData?.user?.fullName ?? "")")
            },
            onFailure: { txnId, error in
                print("Error: \(error)")
            }
        )
    }
}
```

***

## Quick start — UIKit

```swift
import UIKit
import VLensLib

class VerificationViewController: UIViewController, VLensDelegate {
    private var vlensManager: VLensManager!

    func startVerification(accessToken: String) {
        vlensManager = VLensManager(
            transactionId: UUID().uuidString,
            apiKey: "YOUR_API_KEY",
            secretKey: "",
            tenancyName: "YOUR_TENANCY_NAME",
            language: "en"
        )
        vlensManager.setAccessToken(accessToken)
        vlensManager.delegate = self
        vlensManager.present(on: self, withLivenessOnly: false)
    }

    func didValidateSuccessfully(transactionId: String,
                                 userData: VerifyIdBackPost.DataClass?) {
        print("Success: \(transactionId)")
        print("Name: \(userData?.user?.fullName ?? "N/A")")
    }

    func didFailToValidate(transactionId: String, error: String) {
        print("Failed: \(error)")
    }
}
```

***

## Configuration parameters

| Parameter                   | Type          | Required | Default | Description                                          |
| --------------------------- | ------------- | -------- | ------- | ---------------------------------------------------- |
| `transactionId`             | `String`      | Yes      | —       | Unique identifier for the transaction                |
| `apiKey`                    | `String`      | Yes      | —       | Your tenant API key                                  |
| `secretKey`                 | `String`      | Yes      | `""`    | Secret key — pass empty string when using token auth |
| `tenancyName`               | `String`      | Yes      | —       | Your tenant name                                     |
| `accessToken`               | `String`      | Yes      | —       | Bearer token from the Login API                      |
| `language`                  | `String`      | No       | `"en"`  | UI language — `"en"` or `"ar"`                       |
| `withLivenessOnly`          | `Bool`        | No       | `false` | Skip ID capture — liveness check only                |
| `noOfRetries`               | `Int`         | No       | `5`     | Liveness retry attempts before failure               |
| `allowAutoCapture`          | `Bool`        | No       | `true`  | Enable automatic document scanning                   |
| `allowNonTrueDepthFallback` | `Bool`        | No       | `false` | Allow operation on non-TrueDepth devices             |
| `showCloseButton`           | `Bool`        | No       | —       | Show a close/dismiss button                          |
| `colors`                    | `VLensColors` | No       | default | Custom colour theme                                  |
| `onDismiss`                 | `() -> Void`  | No       | `nil`   | Called when the close button is tapped               |

***

## Verification modes

#### Full verification (default)

Runs the complete flow: ID front → ID back → liveness.

```swift
.vlensVerification(
    isPresented: $showVLens,
    transactionId: transactionId,
    apiKey: "YOUR_API_KEY",
    secretKey: "",
    tenancyName: "YOUR_TENANCY_NAME",
    accessToken: accessToken,
    onSuccess: { txnId, userData in },
    onFailure: { txnId, error in }
)
```

#### Liveness only

```swift
.vlensVerification(
    isPresented: $showVLens,
    transactionId: transactionId,
    apiKey: "YOUR_API_KEY",
    secretKey: "",
    tenancyName: "YOUR_TENANCY_NAME",
    withLivenessOnly: true,
    accessToken: accessToken,
    onSuccess: { txnId, userData in },
    onFailure: { txnId, error in }
)
```

#### Sheet presentation

Present the SDK as a sheet using `VLensVerificationView` directly:

```swift
.sheet(isPresented: $showVLens) {
    VLensVerificationView(
        transactionId: transactionId,
        apiKey: "YOUR_API_KEY",
        secretKey: "",
        tenancyName: "YOUR_TENANCY_NAME",
        accessToken: accessToken,
        showCloseButton: true,
        onSuccess: { txnId, userData in
            showVLens = false
        },
        onFailure: { txnId, error in
            showVLens = false
        },
        onDismiss: {
            showVLens = false
        }
    )
}
```

***

## Custom branding

```swift
let customColors = VLensColors(
    light: VLensColorConfig(
        accent: "#007AFF",
        primary: "#1E3A5F",
        secondary: "#666666",
        background: "#FFFFFF",
        dark: "#1C1C1E",
        light: "#F2F2F7"
    ),
    dark: VLensColorConfig(
        accent: "#0A84FF",
        primary: "#FFFFFF",
        secondary: "#ABABAB",
        background: "#1C1C1E",
        dark: "#000000",
        light: "#2C2C2E"
    )
)
```

Pass `customColors` to the `colors` parameter of your `VLensColors` config.

***

## Obtaining an access token

Call the Login API before launching the SDK:

```
POST https://api.vlenseg.com/api/DigitalIdentity/Login
```

**Headers:**

```
Content-Type: application/json
ApiKey: YOUR_API_KEY
TenancyName: YOUR_TENANT
```

**Body:**

```json
{
  "geoLocation": { "latitude": "30", "longitude": "30" },
  "imei": "device_identifier",
  "phoneNumber": "+20XXXXXXXXXX",
  "password": "your_password",
  "smsProviders": 0
}
```

Extract `data.accessToken` from the response and pass it to the SDK.

***

## What's new in v1.4.4

* GIF background tinting applies accent colour across all start and loading screens
* Icon backgrounds tinted consistently behind ID and face vector images
* `loadingTitleLabel` outlets wired in NationalIdBack and ValidationMain screens

See all releases on [GitHub](https://github.com/Vlens2021/vlens-ios-sdk/releases).

***

## Support

For issues or inquiries, contact [support@vlenseg.com](mailto:support@vlenseg.com) with your tenant name, the error message, and the SDK version.