VI iOS SDK Upgrade

This guide walks you through upgrading your iOS app from the VideoIdent (VI) SDK to the DocIDV SDK. The DocIDV SDK introduces a significantly simpler integration model — there is no separate initialization step, no IDnowController, and results are delivered through an error thrown in case of an error.

What has changed

Initialization

The VI SDK required you to create an IDnowSettings object with your companyID and transactionToken, then initialize an IDnowController and wait for a success callback before you could start an identification.

The DocIDV SDK has no initialization step. You call start() directly when you have an ident token.

Starting an identification

The VI SDK used a two-step flow (initialize → startIdentification). DocIDV combines this into a single start() call.

Before (VI SDK)

// Step 1: initialize
let settings = IDnowSettings(companyID: "my_company", transactionToken: "DEV-12345")
let controller = IDnowController(settings: settings)

controller.initialize { success, error, canceledByUser in
    if let error = error {
        // handle error
    } else if success {
        // Step 2: start only after successful init
        controller.startIdentification(from: self) { success, error, canceledByUser in
            // handle result
        }
    }
}

After (DocIDV SDK)

do {
    try await IDnowDocIDV.shared.start(token: "DEV-12345", viewController: viewController)
    // Handle success
} catch let error {
    // Handle errors
}

Optional parameters on start():

• isRoutedSession — set to true if the session is routed from web, allowing the user to resume from where they left off.
• preferredLanguage — language code (e.g. "en", "de") to override the device language.

Handling results

The VI SDK delivered results through either a closure or a delegate pattern, using Bool success, NSError?, and Bool canceledByUser arguments.

The DocIDV SDK throws an IDnowDocIDVError in case of an error.

Before (VI SDK — closure)

controller.startIdentification(from: self) { success, error, canceledByUser in
    if canceledByUser {
        // user cancelled
    } else if let error = error {
        // check error.code against IDnowError constants
    } else if success {
        // success
    }
}

Before (VI SDK — delegate)

// implement IDnowControllerDelegate
func idnowControllerDidFinishIdentification(_ controller: IDnowController) { }
func idnowControllerCanceledByUser(_ controller: IDnowController) { }
func idnowController(_ controller: IDnowController, identificationDidFailWithError error: NSError) { }

After (DocIDV SDK)

do {
    try await IDnowDocIDV.shared.start( 
        token: "YOUR_TOKEN",
        viewController: viewController)
    handleSuccess()
} catch let error {
    switch error {
        case .cancelled(let reason, let message): handleCancellation(message: message)
        case .token(let tokenError, let message): handleTokenError()
        case .network(let networkError, let message): handleNetworkError()
        case .internalError(let statusCode, let message): handleError(statusCode: statusCode, message: message)
    }
}

UI customisation

In the VI SDK, UI customisation required build-time changes in your app using IDnowAppearance.

In the DocIDV SDK, no build-time customisation is required. Your branding and theme configuration is managed centrally by IDnow and applied automatically at runtime. Contact your IDnow Customer Success representative to set up or update your theme.

Settings no longer available

The following VI SDK settings are not available in the DocIDV SDK:

VI SDK setting	What to do
IDnowSettings.companyID	No longer required. The SDK resolves your account from the ident token.
IDnowSettings.transactionToken	Pass the token directly to the start() method.
IDnowSettings.environment	The environment is resolved automatically from the ident token prefix.
IDnowSettings.userInterfaceLanguage	Use the preferredLanguage parameter in the start() method instead.
IDnowSettings.showVideoOverviewCheck	Terms & Conditions screens can be configured through your IDnow customer configuration.
IDnowSettings.showErrorSuccessScreen	Success screens are no longer part of the SDK. Implement them in your own app. Failure screens are always shown.
IDnowSettings.certificateProvider / dtlsCertificateProvider	Custom certificate providers are not yet supported in the DocIDV SDK.
IDnowAppearance	Remove all appearance customisation code. Branding is managed server-side.

---

Upgrade steps

1. Remove the VI SDK

Remove the VI SDK from your project and clean up all related code:

• Remove IDnowSettings and IDnowController usage
• Remove NSError-based error handling and replace with enum-based result handling
• Remove companyID, environment, and connection configurations
• Remove all IDnowAppearance customisation code

2. Add the DocIDV SDK via Swift Package Manager

Add the following package URL in Xcode under File → Add Package Dependencies:

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

3. Integrate the DocIDV SDK

Replace your VI SDK integration with the following:

import DocIDV

func startIdentificationFlow() async {
    do {
        try await IDnowDocIDV.shared.start(token: "YOUR_TOKEN", viewController: viewController)
        handleSuccess()
    } catch let error {
        switch error {
        case .cancelled(let reason, let message): handleCancellation(message: message)
        case .token(let tokenError, let message): handleTokenError()
        case .network(let networkError, let message): handleNetworkError()
        case .internalError(let statusCode, let message): handleError(statusCode: statusCode, message: message)
        }
    }
}

4. Build and run

Build the project and verify the integration is working correctly.

tip

For full SDK configuration options and API reference, see the iOS SDK documentation.