Trulioo KYC Documents iOS Guide

Use this guide when integrating the hosted Trulioo KYC Documents flow into an iOS app.

This guide covers the public Swift package, initialization, hosted UI launch, callback handling, transaction-owned configuration, and support evidence. For host-owned camera composition, use the Capture iOS guide.

If you are already using the legacy DocV iOS 2.x SDK, read KYC Documents iOS 3.0 Migration Guide before applying the current integration steps in this document.

The Trulioo KYC Documents iOS SDK provides a hosted document verification flow for iOS applications.

Customer applications can expect the SDK to:

• initialize a shortcode-backed document verification transaction
• launch hosted document and selfie capture screens through SwiftUI or UIKit
• apply transaction configuration resolved for the active shortcode
• handle capture, image verification, acceptance, and submission inside the hosted flow
• return completion and handled-error callbacks for host routing and support

A standard iOS KYC Documents integration looks like this:

1. add the TruliooKYCDocuments Swift package
2. create a Trulioo instance
3. call initialize(shortcode:completion:)
4. launch the hosted flow with either launch(callbacks:) for SwiftUI or launchController(callbacks:) for UIKit
5. handle completion and error callbacks from the hosted flow
6. call reset() when the host app is done with the transaction or wants to start over

• GitHub repository: https://github.com/Trulioo/kyc-documents
• package name: TruliooKYCDocuments
• Swift package product: TruliooKYCDocuments
• minimum iOS version: 15.0

The published package includes the hosted KYC Documents UI flow for iPhone and resolves its Trulioo and TruliooKYCDocumentsCapture dependencies through the package release metadata.

Host applications must:

• provide a valid KYC Documents shortcode created by the Trulioo customer handoff flow through the Customer API 3.0 handoff operation
• initialize the SDK before launching the hosted UI
• decide whether to embed the hosted flow through SwiftUI or UIKit
• handle completion and structured error callbacks

The SDK owns:

• the document and selfie capture experience
• country, document, and jurisdiction selection
• capture submission and completion screens
• the portrait presentation of the hosted flow

Add the package:

dependencies: [
    .package(url: "https://github.com/Trulioo/kyc-documents.git", from: "X.Y.Z")
]

For beta builds, pin the prerelease tag explicitly:

dependencies: [
    .package(url: "https://github.com/Trulioo/kyc-documents.git", exact: "X.Y.Z-beta.N")
]

Then link the product:

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "TruliooKYCDocuments", package: "kyc-documents")
    ]
)

Import the module you use:

import TruliooKYCDocuments

If your existing integration still uses CocoaPods TruliooDocV, TruliooDelegate, or TruliooWorkflow, use KYC Documents iOS 3.0 Migration Guide to update the distribution and lifecycle contract first.

Initialize first, then launch the hosted SwiftUI view after the transaction is authorized:

import SwiftUI
import TruliooKYCDocuments

struct HostedDocsView: View {
    @State private var trulioo = Trulioo()
    @State private var isAuthorized = false

    let shortcode: String

    var body: some View {
        Group {
            if isAuthorized {
                trulioo.launch(
                    callbacks: TruliooCallbacks(
                        onComplete: { _ in
                            isAuthorized = false
                            trulioo.reset()
                        },
                        onError: { _ in
                            isAuthorized = false
                            trulioo.reset()
                        }
                    )
                )
                .ignoresSafeArea()
            } else {
                Button("Start verification") {
                    trulioo.initialize(shortcode: shortcode) { result in
                        if case .authorized = result {
                            isAuthorized = true
                        }
                    }
                }
            }
        }
    }
}

Initialize first, then present the hosted view controller after the transaction is authorized:

import TruliooKYCDocuments
import UIKit

final class DocsHostViewController: UIViewController {
    private let trulioo = Trulioo()

    func startVerification(shortcode: String) {
        trulioo.initialize(shortcode: shortcode) { [weak self] result in
            guard let self else { return }

            guard case .authorized = result else {
                print("Initialize failed:", result)
                return
            }

            let controller = self.trulioo.launchController(
                callbacks: TruliooCallbacks(
                    onComplete: { _ in
                        self.dismiss(animated: true)
                        self.trulioo.reset()
                    },
                    onError: { _ in
                        self.dismiss(animated: true)
                        self.trulioo.reset()
                    }
                )
            )
            controller.modalPresentationStyle = .fullScreen
            self.present(controller, animated: true)
        }
    }
}

Main entry points:

• Trulioo.initialize(shortcode:completion:) Start or resume the active KYC Documents transaction and authorize the hosted flow.
• Trulioo.launch(callbacks:) Return the hosted KYC Documents SwiftUI view after initialization succeeds.
• Trulioo.launchController(callbacks:) Return a hosted UIViewController for UIKit presentation after initialization succeeds.
• Trulioo.reset() Clear local Docs state after completion, error, or abandonment.

Main result and callback types:

• TruliooResult.authorized(transactionId:) Returned from initialize(...) when the transaction is ready to launch.
• TruliooResult.complete(transactionId:) Used by the SDK callback surface when the hosted flow completes.
• TruliooResult.error(message:details:code:transactionId:) Used by the SDK callback surface when the hosted flow ends with a structured product error.
• TruliooCallbacks Host-provided completion and error handlers for the launched flow.

initialize(shortcode:completion:):

1. authorizes the active KYC Documents transaction from the shortcode
2. loads transaction configuration for the hosted flow
3. prepares the internal Capture-backed UI state
4. returns .authorized(transactionId:) when the flow is ready to launch

Initialization must succeed before calling launch(...) or launchController(...).

The standard hosted-flow sequence is:

1. create a Trulioo instance
2. call initialize(shortcode:completion:)
3. wait for .authorized(transactionId:)
4. launch the hosted flow using SwiftUI or UIKit
5. wait for onComplete or onError
6. call reset()

The host application does not manage camera rendering directly in the KYC Documents SDK. The hosted flow owns that UI internally.

The Device Intelligence send and debug wait paths do not apply to the hosted KYC Documents SDK. The hosted flow owns capture, submission, and completion for the active KYC Documents transaction. The host application handles the terminal callback result.

The host application owns:

• the shortcode
• SwiftUI or UIKit presentation state around the hosted flow
• completion, error, retry, and navigation behavior
• deciding when to call reset()

The SDK owns:

• authorization of the active KYC Documents transaction
• hosted document and selfie capture UI
• transaction-scoped selection and capture rules
• hosted-flow completion and structured error callbacks

The public iOS KYC Documents contract does not require host-side polling configuration.

Important defaults:

• initialize(...) must return .authorized(transactionId:) before launch
• the hosted flow owns document and selfie capture sequencing
• transaction configuration controls locale, branding, capture requirements, and desktop-to-mobile behavior
• reset() clears local SDK state and should be called before starting a new transaction

Use TruliooCallbacks to react to the launched flow:

let callbacks = TruliooCallbacks(
    onComplete: { transactionId in
        print("Completed transaction:", transactionId ?? "missing")
    },
    onError: { result in
        print("Hosted flow error:", result)
    }
)

Recommended host behavior:

• treat onComplete as the terminal success callback
• treat onError as the terminal handled-error callback
• call reset() after either path once the host app is done with the transaction

The iOS KYC Documents SDK can participate in desktop-to-mobile flows when the transaction is configured for cross-device handoff.

In that flow:

• the user starts on desktop
• the user scans the QR code with a mobile device
• the mobile device launches the hosted KYC Documents flow
• the hosted flow continues the document and selfie steps on iPhone

Desktop-to-mobile behavior is configured through the Trulioo customer transaction, not through a separate iOS SDK flag.

The hosted KYC Documents SDK does not accept direct host-side theme or locale objects through the public iOS launch surface.

These settings come from the transaction configuration associated with the shortcode:

• locale
• theme colors and branding
• selection and capture rules
• desktop-to-mobile enablement

• always initialize with a shortcode created for the active KYC Documents transaction
• do not reuse a stale shortcode after reset()
• shortcode environment is selected by the Trulioo customer handoff flow

• Initialization fails immediately: Verify the shortcode is valid and belongs to the expected environment.
• The hosted UI does not appear: Confirm launch(...) or launchController(...) is only used after .authorized.
• The flow completes but the host stays on the SDK screen: Handle onComplete and dismiss or swap screens in the host app.
• The flow returns an error result: Log the returned message, code, and transactionId when present.

When escalating an iOS KYC Documents issue, collect:

• KYC Documents SDK version
• iPhone model and iOS version
• shortcode environment used for testing
• returned transaction id when available
• whether the flow was pure mobile or desktop-to-mobile
• whether the host used SwiftUI or UIKit launch
• the final TruliooResult or callback payload

When handing an issue to Trulioo support, include:

• the package version and release channel
• the shortcode environment, without sharing secrets in public tickets
• device model, iOS version, and host presentation mode
• whether initialization reached .authorized(transactionId:)
• final callback result and transaction id when available
• whether reset() was called before retrying the transaction