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

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:

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

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.

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

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.

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

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