Trulioo SDK - iOS Guide

Quick Summary

The Trulioo iOS SDK initializes a shortcode-backed session and exposes base verification capabilities for iOS applications.

Customer applications can expect the SDK to:

• resolve session configuration and authorization from the active shortcode
• support configured Device Intelligence capabilities
• return iOS-native results, identifiers, errors, and diagnostic trace data for host routing and support

A standard iOS integration looks like this:

1. add the Trulioo Swift package
2. initialize with a shortcode
3. collect Device Intelligence when required by the journey
4. use the result to continue, retry, or route the journey for review

Package And Compatibility

• public-facing product name: Trulioo
• Swift package product: Trulioo
• package name: Trulioo
• minimum iOS version: 15.0

Installation

Add the package:

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

For beta builds, depend on the prerelease tag explicitly:

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

Then link the product:

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "Trulioo", package: "Trulioo")
    ]
)

Before You Start

Before using the SDK, make sure the host application:

• has a valid shortcode generated through the Trulioo customer handoff flow using the Customer API 3.0 handoff operation
• uses a shortcode configured for Device Intelligence when required by the journey
• initializes a new SDK session for each verification journey

Initialization

iOS initialization is callback-based over async work:

Trulioo.initialize(
    shortcode: shortcode,
    onComplete: { result in
        // Persist the result for later collection
    },
    onError: { error in
        // Initialization failed
    }
)

What Initialization Does

Initialization:

1. resolves the service host from the shortcode
2. establishes an authorized SDK session
3. retrieves the session configuration
4. retains Device Intelligence configuration for later native collection when enabled
5. returns the initialization result for the current verification journey

Initialization Result

The onComplete callback receives the current Trulioo.InitializationResult.

The SDK retains the session configuration, resolved service host, and authorization token internally for the active session. Call reset() to clear that session before starting another journey.

Verification Capabilities

Beta - changes are possible.

Threading Requirement

The following API is annotated @MainActor and must be called from the main thread (or with await MainActor.run {}):

• Trulioo.reset()

Calling it from a background task without @MainActor context will produce a compiler warning or runtime error.

Device Intelligence

Use Device Intelligence when your iOS flow needs device-risk telemetry from the current app session.

Choose An Integration Mode

Recommended: collectDeviceIntelligence(...)

The normal iOS sequence is:

1. initialize once
2. call collectDeviceIntelligence(...) when the host needs an explicit device result
3. inspect the lifecycle status and diagnostics

For most integrations, use collectDeviceIntelligence(...). It performs collection, submission, and polling in one async call. It returns a terminal event when processing completes or fails; if the configured polling limit is reached first, it returns the latest non-terminal lifecycle event and records the timeout in debugTrace.

If polling exhausts, the result contains the last non-terminal lifecycle state and debugTrace contains a device_event_terminal timeout entry. Wait and retrieve the detailed result only after the status is .completed. If the event fails, use deviceEvent.failureReason for the failure detail.

Explicit collection example:

Trulioo.initialize(
    shortcode: shortcode,
    onComplete: { initialized in
        Task {
            let result = try await Trulioo.collectDeviceIntelligence(
                polling: DeviceIntelligencePollingOptions()
            )

            print("device event", result.deviceEvent)

            if result.deviceEvent?.status == .completed {
                let eventId = result.deviceEvent?.eventId
                let transactionId = result.deviceEvent?.transactionId
            }
        }
    },
    onError: { error in
        print(error)
    }
)

collectDeviceIntelligence(...) returns an enriched Trulioo.InitializationResult for the same session.

Background Submission: sendDeviceInformation(...)

Use sendDeviceInformation(...) when the application should submit DI without waiting for server evaluation or a final risk result.

let submission = try await Trulioo.sendDeviceInformation()

It returns after Trulioo accepts the event, rather than waiting for a terminal DI outcome.

The submission result is one of two cases.

Accepted Response Fields

Failed Response Fields

Retrieve the Detailed Result

Both integration modes provide transactionId after submission. Call GET /transactions/{transactionId}/devices with that value after device processing is complete to retrieve the detailed device result.

• collectDeviceIntelligence(...) normally returns after reaching .completed or .failed. If its configured polling limit is reached first, it returns the latest non-terminal lifecycle state and records the timeout in debugTrace.
• sendDeviceInformation(...) returns after Trulioo accepts the event, before evaluation completes.

Retrieve details after the event is .completed. If collectDeviceIntelligence(...) returns a non-terminal status, wait and retry the endpoint until processing completes.

See Get transaction devices for authentication, request requirements, and the detailed result fields.

Device Intelligence Options

Device Intelligence options customize explicit DI collection. They are optional; the SDK manages the device runtime automatically.

collectDeviceIntelligence(...) accepts optional polling controls:

Provide options directly to explicit collection:

let result = try await Trulioo.collectDeviceIntelligence(
    polling: DeviceIntelligencePollingOptions(
        maxAttempts: 10,
        intervalMilliseconds: 1000
    )
)

Resetting State

Call Trulioo.reset() to clear all internal session state. Use this for logout flows or before re-initializing with a new shortcode:

Trulioo.reset()
// Can now call Trulioo.initialize(...) again

Error Handling

Not-initialized errors:

• NotInitializedError is thrown when calling any method before initialize() completes or after reset()
• Affected method: collectDeviceIntelligence

Initialization errors are delivered through the onError callback.

Send errors:

• return SendDeviceInformationResult.failed
• include a stable failure code, failed stage, message, identifiers when known, and debugTrace

Device collection throws on failure. When troubleshooting, inspect:

• the thrown error
• deviceEvent?.failureReason
• debugTrace

Troubleshooting

If Device Intelligence does not appear:

1. Confirm initialization completed successfully.
2. Confirm Device Intelligence is enabled for the account and verification journey.
3. Confirm you explicitly called collectDeviceIntelligence(...) or sendDeviceInformation(...).
4. Inspect debugTrace.

If results are incomplete:

1. Inspect deviceEvent?.failureReason.
2. Inspect debugTrace for a polling timeout or failed stage.
3. After the event completes, retrieve the detailed result with GET /transactions/{transactionId}/devices.