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 — a passive face scan (blink plus natural head movement) runs automatically after identity verification, with no step-by-step prompts
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 upload retry — transient upload failures are retried internally

Requirements

iOS 16.0 or later
Swift 5.9 or later
Xcode 15 or later
A physical device that supports ARKit face tracking. Liveness gates on ARFaceTrackingConfiguration.isSupported, which covers iPhone X and later as well as A12 and later devices without a TrueDepth camera. Liveness cannot run in the Simulator

Installation

The SDK is distributed via Swift Package Manager as a precompiled XCFramework. The package you add contains the Swift Package manifest; Xcode downloads the binary automatically and embeds it in your app.

Xcode (recommended)

Open your project in Xcode
Go to File → Add Package Dependencies
Enter the repository URL: https://github.com/386konsult/smartcomply-ios-sdk
Select Up to Next Major Version and enter 1.0.2
Click Add Package and select the SmartComplySDK library

Package.swift

dependencies: [
    .package(url: "https://github.com/386konsult/smartcomply-ios-sdk", from: "1.0.2")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "SmartComplySDK", package: "smartcomply-ios-sdk")
        ]
    )
]

The package URL is smartcomply-ios-sdk, which is not the same as the SDK’s source repository. It ships both device and simulator slices, so the same dependency builds for a physical device and the Simulator without extra configuration.

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>

This is the only usage-description key the SDK needs. It records no audio, and the Upload from library control uses PHPickerViewController, which runs out of process and requires no photo-library key.

Credentials

Both values come from your Adhere Dashboard and both are permanent. Reuse the same pair for every verification.

Value	Where to find it	Notes
`apiKey`	Settings → API Keys	A 64-character alphanumeric string with no prefix
`clientId`	Settings → Integrations → SDK Setup, then the row menu → Integration → Client ID	The UUID of your SDK Config. It is issued by Adhere — do not generate one

clientId is not a per-attempt value. Generating your own UUID returns 404 SDK_CONFIG_NOT_FOUND on the very first call, because the server resolves it against an existing SDK Config record.

Quick Start

1. Create the SDK instance

Create a SmartComply instance once, for example in your view model or app entry point.

import SmartComplySDK

let sdk = SmartComply(
    config: SDKConfig(
        apiKey:      "YOUR_API_KEY",
        clientId:    "YOUR_CLIENT_ID",
        environment: .production
    )
)

Always pass environment explicitly. SDKConfig defaults to .sandbox, which points at http://localhost:8000 — see Environments.

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:      "YOUR_API_KEY",
            clientId:    "YOUR_CLIENT_ID",
            environment: .production
        )
    )

    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)   // "processing"
            }
        }
    }
}

The SDK manages the entire flow automatically. The exact steps depend on the verification mode configured in your Dashboard: Document mode (photo capture):

Creates a secure session
Displays a welcome screen with your brand name and ID type cards
Shows a country picker if multiple countries are configured
User photographs the front of their ID inside the guide box
Photographs the back if the ID type’s name contains national, driver, resident or voter
Runs the passive liveness scan
Returns a FlowResult to your completion handler

Data mode (ID number entry):

Creates a secure session
Displays a welcome screen with ID type selection
Shows a country picker if multiple countries are configured
User enters their ID number and any required fields
Identity is verified against the national database
Runs the passive liveness scan
Returns a FlowResult to your completion handler

Environments

Value	Base URL
`.production`	`https://adhere-api.smartcomply.com`
`.sandbox`	`http://localhost:8000`

.sandbox targets a server running on the device itself, for local backend development. It is not a hosted test environment. Use .production for all integration work.

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 Adhere API key (required)
`clientId`	—	Your SDK Config’s Client ID (required)
`environment`	`.sandbox`	Set this explicitly — see Environments
`requestTimeout`	`30`	Timeout in seconds for standard API calls, including identity verification
`uploadTimeout`	`120`	Timeout in seconds for image and video upload
`maxUploadRetries`	`3`	Total upload attempts, not retries after the first. Only transport failures are retried; an API error is surfaced immediately
`debug`	`false`	Writes verbose network logs to the unified log (`os.Logger`, subsystem `com.smartcomply.sdk`) when `true`. Read them in Console.app — they do not appear in Xcode’s console pane

FlowResult

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

public struct FlowResult {
    public let entryId: Int                              // verification entry ID
    public let status: String                            // "processing"
    public let submittedAt: String?                      // ISO 8601 timestamp
    public let verificationResult: VerifyIdentityResponse? // data mode only
    public let idTypeName: String?                       // e.g. "National Identity Number (NIN)"
    public let verifiedName: String?                     // see the note below
    public let idNumber: String?                         // see the note below
}

verifiedName and idNumber are always nil on 1.0.1 and earlier, in both verification modes. If you are pinned to one of those versions, read the verified identity from the webhook payload instead and do not build UI that depends on these two properties. Upgrade to 1.0.2.

From 1.0.2 both are populated. In document verification they come from the OCR of the captured document; in data verification they come from the identity provider’s response. verifiedName is the full name where the provider sends one, otherwise it is composed from the first, middle and last name fields.They are still only as good as the submission that produced them, so treat them as a receipt of what was read, not as a verdict. The webhook remains the source of truth for the final outcome.

The result is a submission receipt, not a verification verdict. status is "processing" when the user finishes: face matching, document OCR and the government database check all continue after onComplete fires. An entry’s status moves through pending, processing, and then passed, failed or expired. The final status, the extracted fields and any failure reason are delivered to the webhook URL configured on your SDK Config. See Webhooks for the full payload.

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.errorCode ?? "-")]:", error.message)
} catch {
    print("Network error:", error.localizedDescription)
}

SDKError exposes message: String, statusCode: Int and errorCode: String?. AuthError and NetworkError both subclass it, so a single catch let error as SDKError covers every case.

Scenario	Cause	Resolution
`401`, `errorCode` `AUTH_ERROR`	Invalid or missing API key. Every authentication failure, including a `403`, is reported with this code and a status of `401`	Check your key in the Adhere Dashboard
`404`, `errorCode` `SDK_CONFIG_NOT_FOUND`	`clientId` is not an active SDK Config	Copy the Client ID from Settings → Integrations → SDK Setup. Do not generate a UUID
Session expired	Session tokens live 30 minutes	Present the flow again. A new session is created each time; your `clientId` never changes
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

​SmartComply iOS SDK

​Features

​Requirements

​Installation

​Xcode (recommended)

​Package.swift

​Platform Setup

​Credentials

​Quick Start

​1. Create the SDK instance

​2. Present the flow view

​Environments

​SDK Configuration

​FlowResult

​Error Handling

SmartComply iOS SDK

Features

Requirements

Installation

Xcode (recommended)

Package.swift

Platform Setup

Credentials

Quick Start

1. Create the SDK instance

2. Present the flow view

Environments

SDK Configuration

FlowResult

Error Handling