> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartcomply.com/llms.txt
> Use this file to discover all available pages before exploring further.

# iOS SDK

> Integrate SmartComply identity verification and liveness detection into your iOS app with a single drop-in SwiftUI view.

# SmartComply iOS SDK

The SmartComply iOS SDK is a native Swift library that delivers a fully self-contained identity verification flow for iOS apps. Drop in one SwiftUI view and the SDK handles session management, country and ID-type selection, document capture, identity verification, and liveness detection automatically.

## Features

* **Drop-in SwiftUI view** — `SmartComplyFlowView` manages the entire verification flow with no UI code required
* **Two verification modes** — document photo capture or ID number data entry, configured from your Dashboard
* **Guide-box document capture** — crops exactly what falls inside the ID card frame so the image sent to the backend is always clean
* **Liveness detection** — face challenge system (blink, turn head) runs automatically after identity verification
* **Dynamic ID types** — channels and fields are fetched live from your Dashboard configuration
* **Multi-country support** — renders a country picker automatically when more than one country is configured
* **Dark and light mode** — theme adapts to the system colour scheme; override with `preferredColorScheme`
* **Automatic retry** — handles upload retries and session errors internally

***

## Requirements

* **iOS 16.0** or later
* **Swift 5.9** or later
* **Xcode 15** or later
* **iPhone X or later** — liveness detection requires a front-facing TrueDepth camera

***

## Installation

The SDK is distributed via Swift Package Manager.

### Xcode (recommended)

1. Open your project in Xcode
2. Go to **File → Add Package Dependencies**
3. Enter the repository URL: `https://github.com/386konsult/ios-sdk`
4. Select **Exact Version** and enter `1.0.0`
5. Click **Add Package** and select the **SmartComplySDK** library

### Package.swift

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/386konsult/ios-sdk", exact: "1.0.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "SmartComplySDK", package: "ios-sdk")
        ]
    )
]
```

***

## Platform Setup

Add the following key to your app's `Info.plist`:

```xml theme={null}
<key>NSCameraUsageDescription</key>
<string>Camera access is required to photograph your ID document and complete liveness verification.</string>
```

***

## Quick Start

### 1. Create the SDK instance

Create a `SmartComply` instance once — for example in your view model or app entry point. Generate a fresh `clientId` (UUID) for each new verification attempt.

```swift theme={null}
import SmartComplySDK

let sdk = SmartComply(
    config: SDKConfig(
        apiKey:      "pk_live_xxxxxxxxxxxx",
        clientId:    UUID().uuidString,       // unique per verification attempt
        environment: .production
    )
)
```

### 2. Present the flow view

Embed `SmartComplyFlowView` anywhere in your SwiftUI hierarchy. The SDK loads automatically when the view appears.

```swift theme={null}
import SmartComplySDK

struct ContentView: View {
    @State private var showVerification = false
    let sdk = SmartComply(config: SDKConfig(apiKey: "pk_live_...", clientId: UUID().uuidString))

    var body: some View {
        Button("Verify Identity") {
            showVerification = true
        }
        .fullScreenCover(isPresented: $showVerification) {
            SmartComplyFlowView(sdk: sdk) { result in
                showVerification = false
                print("Entry ID:", result.entryId)
                print("Status:", result.status)
                if let name = result.verifiedName {
                    print("Verified name:", name)
                }
            }
        }
    }
}
```

The SDK manages the entire flow automatically. The exact steps depend on the verification mode configured in your Dashboard:

**Document mode** (photo capture):

1. Creates a secure session
2. Displays a welcome screen with your brand name and ID type cards
3. Shows a country picker if multiple countries are configured
4. User photographs the front of their ID inside the guide box
5. Photographs the back if required (National ID, Driver's Licence, Voter's Card)
6. Runs liveness face challenges
7. Returns a `FlowResult` to your completion handler

**Data mode** (ID number entry):

1. Creates a secure session
2. Displays a welcome screen with ID type selection
3. Shows a country picker if multiple countries are configured
4. User enters their ID number and any required fields
5. Identity is verified against the national database
6. Runs liveness face challenges
7. Returns a `FlowResult` to your completion handler

***

## SDK Configuration

```swift theme={null}
public struct SDKConfig {
    public init(
        apiKey: String,
        clientId: String,
        environment: SDKEnvironment = .sandbox,
        requestTimeout: TimeInterval = 30,       // seconds
        uploadTimeout: TimeInterval  = 120,      // seconds
        maxUploadRetries: Int = 3,
        debug: Bool = false
    )
}
```

| Parameter          | Default    | Description                                                                       |
| ------------------ | ---------- | --------------------------------------------------------------------------------- |
| `apiKey`           | —          | Your SmartComply API key (required)                                               |
| `clientId`         | —          | A unique identifier per verification attempt — use `UUID().uuidString` (required) |
| `environment`      | `.sandbox` | `.sandbox` for testing; `.production` for live traffic                            |
| `requestTimeout`   | `30`       | Timeout in seconds for standard API calls                                         |
| `uploadTimeout`    | `120`      | Timeout in seconds for video upload                                               |
| `maxUploadRetries` | `3`        | Number of automatic retry attempts on upload failure                              |
| `debug`            | `false`    | Prints verbose network logs to the console when `true`                            |

***

## FlowResult

Delivered to your `onComplete` closure when the user completes the flow in-app.

```swift theme={null}
public struct FlowResult {
    public let entryId: Int          // liveness entry ID — use this to query results via the API
    public let status: String        // e.g. "submitted"
    public let submittedAt: String?  // ISO 8601 timestamp
    public let idTypeName: String?   // e.g. "National ID", "BVN"
    public let verifiedName: String? // name returned by the identity provider (data mode only)
}
```

> **Final verification results are delivered via webhook.** Once the backend completes processing, SmartComply sends a webhook event to the URL configured in your Dashboard. Set up your webhook endpoint to receive the final status, extracted fields, and any failure reasons. See the [Webhooks](/webhooks) guide for the full payload reference.

***

## Error Handling

`SmartComplyFlowView` handles and displays error states automatically. For the headless API, all SDK methods throw on failure:

```swift theme={null}
do {
    _ = try await sdk.createSession()
} catch let error as SDKError {
    print("API error \(error.statusCode):", error.message)
} catch {
    print("Network error:", error.localizedDescription)
}
```

| Scenario                    | Cause                                                 | Resolution                                                       |
| --------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------- |
| `401 Unauthorized`          | Invalid or missing API key                            | Check your key in the SmartComply Dashboard                      |
| Session expired             | Sessions expire after 2 hours and are single-use      | Generate a new `clientId` and call `createSession()` again       |
| Camera permission denied    | User denied camera access                             | The flow view shows a Settings deep-link automatically           |
| Upload failed after retries | Network instability                                   | `maxUploadRetries` exhausted — the failure screen offers a retry |
| Identity not found          | ID number not found or details mismatched (data mode) | User is shown the reason and prompted to re-enter                |