iOS SDK

Integrate the TrustPlatform iOS SDK into your iOS app

This page covers the iOS setup. For what the SDK does and how it fits into your integration, see the Mobile SDK overview.

---

Requirements

Requirement	Minimum version
iOS	15.0
Swift	6.0

These are the Trust Platform SDK's requirements. If you add native document verification, the DocIDV SDK's requirements also apply.

---

Installation

1. In Xcode, select File > Add Package Dependencies…
2. Paste the repository URL:

   https://github.com/idnow/trustplatform-sdk-ios

3. Click Add Package (We recommend setting the version rule to Up to Next Major Version).
4. In the package product selection sheet, add TrustPlatform to your app target. Click Add Package.

Configure Your App

Check which device capabilities your flow needs, then add the matching keys to your Info.plist file. iOS shows each usage description to the user when the app first asks for access, so explain the real reason.

Key	Type	Notes
Privacy - Camera Usage Description	string	Required for document and biometric capture
Privacy - Microphone Usage Description	string	Required for video-based verification steps, such as agent video calls
Privacy - NFC Scan Usage Description	string	Required for NFC chip reading. See native document verification

---

Configure the SDK

Call IDnowTrustPlatform.configure(environment:) once at app startup, before you create a session.

// AppDelegate.application(_:didFinishLaunchingWithOptions:)
// or your @main struct init:
IDnowTrustPlatform.configure(environment: .production)

Environment	Description
.production	The production environment
.sandbox	The sandbox environment for development and testing (default)

Start a Session

1. Create a new session via the /sessions API.
2. Use the session token to initialize a new TPSession instance.
3. Call run(from:) and switch on the returned FlowOutcome.

func startVerification(from viewController: UIViewController) async {
    let session = TPSession(token: sessionToken)
    do {
        switch try await session.run(from: viewController) {
        case .completed:
            // The flow completed. Query your backend for the outcome.
            // See https://docs.eu.platform.idnow.io/docs/integration/get-session-results
        case .aborted:
            // The user aborted the flow.
        @unknown default:
            break
        }
    } catch {
        // Handle technical failures — see Handle Errors below.
    }
}

To abort a running session programmatically, call session.stop().

Session Options

To configure a session, pass a TPSessionOptions value when you create it. Options are fixed when the session is created.

let session = TPSession(
    token: sessionToken,
    options: TPSessionOptions(dismissOnFinish: false)
)

Option	Default	Description
dismissOnFinish	true	When true, the SDK dismisses the flow as soon as it ends, whether it completed, was aborted, or failed. When false, the flow stays on screen until the user closes it: the last screen when the flow ends, or the built-in error screen when it fails.

With either setting, run(from:) returns a FlowOutcome or throws a TrustPlatformError in the same way. Calling session.stop() always dismisses the flow.

Handle Outcomes

run(from:) returns a FlowOutcome value when the flow reaches a terminal state.

Case	When it occurs
.completed	The flow completed successfully
.aborted	The user aborted the flow

By default, the SDK dismisses the flow when it ends. To keep the last screen up until the user closes it, set dismissOnFinish to false.

.completed only signals that the flow finished. To retrieve the actual outcome, query the Get session results API endpoint using the sessionId you received when creating the session. See Interpret session results for how to act on it.

Handle Errors

run(from:) throws a TrustPlatformError when a technical failure prevents the flow from running or completing.

Case	When it occurs
flowFailure	A technical failure occurred within the flow
invalidToken	The session token is not valid for an SDK session
sessionExpired	The session timed out on the server
networkFailure(underlying:)	No connection or a request failed
nativeHandlerFailure(code:message:)	A native handler reported a non-recoverable failure
internalError	An unexpected SDK-internal failure

errorDescription on each case is localized and safe to display to end users.

By default, the SDK dismisses the flow when run(from:) throws, so your app must show the error in its catch block. If you set dismissOnFinish to false, the SDK shows its built-in error screen instead, and the screen stays up until the user closes it.

Native document verification (optional)

The TrustPlatformDocIDV module runs document capture, and NFC chip reading where the flow uses it, as native screens instead of in the webview. It uses IDnow's DocIDV SDK, which the module brings in as a dependency. Sessions, outcomes and data blocks are the same either way. See the Mobile SDK overview.

The DocIDV SDK's requirements apply when you add this module. For details specific to the DocIDV SDK, see the standalone DocIDV SDK documentation.

Add the Framework

1. Select your app target, then open the Frameworks, Libraries, and Embedded Content list.
2. Click + and add TrustPlatformDocIDV from the TrustPlatform package. Swift Package Manager resolves the DocIDV SDK for you.

Configure Your App for NFC

NFC chip reading needs the following entitlement and Info.plist entries. NFC results are processed by the Verifying ID document (v3) step.

Entitlements File

1. Open your app's entitlements file. If you do not have one, select File > New File > Property List and name it YourApp.entitlements.
2. Add a key Near Field Communication Tag Reader Session Formats of type Array.
3. Add one item to the array:
   • Type: String
   • Value: TAG

Info.plist File

1. Open your Info.plist file.
2. Add the key Privacy - NFC Scan Usage Description and enter a string that explains why the app uses NFC.
3. Add the key ISO7816 application identifiers for NFC Tag Reader Session of type Array.
4. Add the following two string items to the array:
   • A00000045645444C2D3031
   • A0000002471001

How It Works

Linking TrustPlatformDocIDV is enough: you do not need to call anything to register it. If the framework is not linked, the SDK runs the document step in the webview instead.