Trulioo iOS SDK

📘

Info

Some US states impose obligations on businesses that collect and use “biometric identifiers” and/or “biometric information”, which may include facial scan data extracted from photos during a document verification transaction. One such law is the Illinois Biometric Information Privacy Act (“BIPA”). A business required to comply with BIPA is under obligations to, among other things, ensure that it informs the individual of the purpose of the collection and obtain consent. Accordingly, we require a notice and consent mechanism be implemented for all document verification transactions, and our customers using our API must provide us with confirmation via API whether an individual is located in the United States and has consented to the transaction in the prescribed manner. We also strongly encourage all of our customers to consult with legal counsel to ensure their own compliance with such laws.

For more information about the required notice and consent mechanism, please refer to our Service Specific Terms for Document Verification.

Overview

The Trulioo iOS SDK facilitates the capture of government-issued identity documents and biometrics for the purpose of identity verification.

Trulioo's sophisticated technology delivers a smooth experience for your end-users, while optimizing for fast and accurate verification.

• The intuitive UI/UX guides your users through the entire photo capture process
• The modular app design allow you to seamlessly connect the image capture process into your own application flow
• Advanced image quality detection leads to higher verification success rates
• Direct image upload to the Trulioo service simplifies integration

Note: The SDK is only responsible for capturing and uploading photos. Access the Trulioo Customer API for authorization and to perform checks.

Compatibility

To use the DocV SDK with the Customer API, please align the versions according to the below compatibility chart.

Getting started

The Trulioo iOS SDK supports:

• iPhones (excluding iPhone SE) running iOS 14+
• Xcode 12+
  • Integration with any project that uses SwiftUI
  • Integration with any project that uses UIKit (Storyboards)
• Bitcode
• ARM64, ARM64-Simulator, & X86-Simulator
• Portrait screen orientation
• Light mode appearance
• RFC 5646 languages tags

1. Obtain a transaction shortcode

In order to start your integrating, you will need an API token and REST API integration outside of the application. You will generate a Shortcode that lasts up to 5 minutes and provide the Shortcode to your application when ready to launch your Document Verification workflow.

Note: You must never use API tokens in the frontend of your application or malicious users could discover them in your source code. You should only use them on your server.

2. Download and install the Trulioo SDK

The Trulioo SDK is available on Swift Package Manager (SPM) & Cocoapods.

Swift Package Manager

https://github.com/Trulioo/docv.git

Cocoapods

pod 'TruliooDocV'

Lottie Animations

If you are installing Trulioo DocV with Cocoapods. For Trulioo DocV 2.4.0 or greater, also add this required block at the end of your podfile to ensure compatibility.

post_install do |installer| 
   installer.pods_project.targets.each do |target| 
      if target.name == 'lottie-ios' 
         target.build_configurations.each do |config|
            config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
            config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'x86_64'
         end 
      end 
   end
end

3. Grant permissions

The SDK requires camera permissions. Ensure the following keys are included in your apps info.plist

<key>NSCameraUsageDescription</key>
<string>To validate your identity, camera access is required.</string>

4. Create the SDK delegate

Once the SDK has been added as a dependency, you can use it in your projects as a library. Import the TruliooSDK library to your ViewController class file, extend your ViewController class with the TruliooDelegate and add the required delegate functions as follows:

import UIKit
import TruliooSDK

class YourViewController : UIViewController, TruliooDelegate {
    func onInitialized() {
        print("SDK Initialized")
    }
    
    func onComplete(result: TruliooSuccess) {
        print("Verification success with transactionID: \(result.transactionId)")
    }

    func onError(error: TruliooError) {
        print("Verification error code: \(error.code), transactionID: \(error.transactionId), message: \(error.message)")
    }

    func onException(exception: TruliooException) {
        print("Verification exception \(exception.message)")
    }
}

5. Initialize the Trulioo SDK

Call the Trulioo().initialize function, and pass in the workflow configuration with the obtained short code and self as the delegate parameter to initialize the SDK:

let workflow = TruliooWorkflow(
  shortcode: "sample-short-code",
  locale: "en-US",
  isDemoMode: false,
  enableRegionSelection: true,
  enableDocumentAutoCapture: true
)

// Initialize the SDK with the workflow configuration
Trulioo().initialize(delegate: self, workflow: workflow)

6. Start a verification flow

Finally, call the Trulioo().launch() function under the onInitialized delegate, and pass in self as the delegate parameter to launch the SDK:

func onInitialized() {
    print("SDK Initialized")
    Trulioo().launch(delegate: self)
}

Example ViewController that launches Trulioo

import UIKit
import TruliooSDK

class YourViewController : UIViewController, TruliooDelegate {
    // Start of Trulioo delegate - Required
    func onInitialized() {
        print("SDK Initialized")
        Trulioo().launch(delegate: self)
    }
    
    func onComplete(result: TruliooSuccess) {
        print("Verification success with transactionID: \(result.transactionId)")
    }

    func onError(error: TruliooError) {
        print("Verification error code: \(error.code), transactionID: \(error.transactionId), message: \(error.message)")
    }

    func onException(exception: TruliooException) {
        print("Verification exception \(exception.message)")
    }
    // End of Trulioo delegate - Required

    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        let workflow = TruliooWorkflow(shortCode: "sample-short-code")

        // Initialize the SDK with the workflow configuration
        Trulioo().initialize(delegate: self, workflow: workflow)
    }
}

Changing Language Locale

Locales are used to set the language of the SDK. This feature is available on version 2.5.0 or greater.

The SDK will default to the user's device setting language locale.

If the given language is available but the given locale is not supported, the SDK will set to the given language and the default supported locale.

If the given language locale is not supported, the SDK will default to English (US).

To set language locale, pass in the desired language as a Locale ID (LCID) short string in the locale parameter of the TruliooWorkflow object.

// Find a list of supported locales (LCID) in the table below.
let workflow = TruliooWorkflow(shortCode: "sample-short-code" , locale: "fr-CA")

Customize Theme

This customizing theme feature is available on version 2.5.0 or greater.

To use a custom theme, the SDK provides the TruliooWorkflowTheme object that allows for some customizations.

To set a desired logo for branding, you can pass in the name of a image asset as a string in the logoAssetName parameter. The provided logo will be displayed with a fixed height of 32 pixels.

To customize the primary buttons colors, you can set the primaryButtonColorName and primaryButtonTextColorName parameters with hex color string values.

let theme = TruliooWorkflowTheme(
    logoAssetName: "Your_Logo",
    primaryButtonColorName: "#172c2d",
    primaryButtonTextColorName: "#a4dbb4")

let workflow = TruliooWorkflow("sample-short-code", theme: theme)

Country and Jurisdiction Selection

Each experience can be customized with specific countries and jurisdictions for each document type.

Use the API endpoint /customer/transactions to configure all the regions you accept.
Please see here for more details on the API reference.

Note: If you specify an empty list for countries OR specify all supported countries, the country list will not appear.
Same applies for the list of jurisdictions.

You can override the regions selection screens and turn them off from the workflow builder.
Change the parameter 'enableRegionSelection' to false and both screens will be hidden from the user.

let workflow = TruliooWorkflow(
  shortcode: "sample-short-code",
  locale: "en-US",
  isDemoMode: false,
  enableRegionSelection: true, // Change this to false to override
  enableDocumentAutoCapture: true
)

Handle the verification result

After a session is completed, callback functions are invoked based on the result of the workflow (see above code block for example):

Additionally, you can utilize getSessionResult function call after completing the verification to get the result with the current result Transaction ID:

Trulioo().getSessionResult() { result in
      print("Transaction status: \(result.status), Transaction ID: \(result.transactionId)")
}

The result object should contain the Transaction ID and the verification status which could be one of the following:

Cancel a verification

It is recommended to complete a verification fully. However, if you wish to cancel an active verification flow, you can do so anytime by calling the close() method. This method will dismiss the SDK from the user’s device and onError() will be called to indicate that the verification has been interrupted. When you are ready to initiate a new verification, you can create a new workflow and launch the SDK again.

Note: using close() is usually not necessary as the SDK will internally call this method when the verification has completed.

Trulioo().close()

// This function will trigger after Trulioo().close()
func onError(error: TruliooError) {
    print("Verification error code: \(error.code), transactionID: \(error.transactionId), message: \(error.message)")
}

Handling verification errors