NAV Navbar
swift
  • Upgrade guide iOS SDK 2.x to 3.x
  • Upgrade guide iOS SDK 2.x to 3.x

    Many things have changed from 2.x to 3.0. One of the main goals for 3.0 is to reduce the overhead for the developer, which means that the framework is much more powerful and takes care of nearly everything. This means that the amount of code the developer has to write has dramatically decreased, making it even easier to implement the SDK.

    Whereas setting up the SDK and letting the user perform a scan required multiple steps, the entry point has been streamlined to only a few calls.

    We will list the steps that were required in 2.x and how to migrate these steps to be compatible with 3.0 The following table lists any renames or changes in how to interact with the SDK:

    Step 2.x 3.x equivalent
    Configure Verifai with a licence Verifai.configure(licence:identifier:) VerifaiCommons.setLicence(licence:)
    Automatic scan Verifai.scanViewController(scanMode: .ai) Verifai.start
    Manual scan Verifai.scanViewController(scanMode: .manual) Verifai.start
    Set styling template Verifai.template(path:) Individually change colors: Styling and theming i.e. UIColor.Verifai.primaryColor = UIColor.blue
    Clear image cache Verifai.clearCache() VerifaiCommons.VerifaiCache.clearCache()
    Clean up Verifai to free memory Verifai.destroy() No longer necessary

    The following table lists the calls to the SDK in 2.x that are no longer applicable and as such do not have an equivalent for 3.0:

    Step 2.x
    Load local models Verifai.setDocumentClassifierNeuralModel
    Load online models Verifai.downloadDocumentClassifierNeuralModels
    Load online OCR models Verifai.downloadOCRMRZNeuralModels
    Cancel all requests Verifai.cancelAllRequests()
    Check the licence status Verifai.checkLicence(responseBlock:)
    Pre-fetch documents for one or more countries Verifai.downloadDocuments(for countries:)
    Get the available document country codes Verifai.downloadCountries()

    Dependencies

    To make the framework easier to use we have dropped some dependencies compared to version 2.x.

    The following dependencies have been removed:

    Feel free to remove these files from your project when upgrading to 3.x.

    Version 3.0 only has the following dependency:

    Starting with version 3.2 there are no external dependencies.

    Setup and loading

    Loading Verifai

    Importing document scanning in Verifai 2.x

    import VerifaiLite
    

    Importing all Verifai core components in 2.x

    import Verifai
    

    Importing Verifai core components in 3.x

    import Verifai
    import VerifaiCommons
    

    Importing all Verifai modules in 3.x

    import Verifai
    import VerifaiCommons
    import VerifaiNFC
    import VerifaiLiveness
    

    The first thing you'll have to look at is how you loaded the framework. Whether manually, or trough Carthage or Cocoapods some steps are needed to update how the framework is loaded into your app. The previous system where there was a Verifai and a VerifaiLite framework has been dropped in favor of individual modules that add specific functionality to your app. If you want to read more info about the new components you can read about it here.

    For a reference on which modules you need to have please consult the table below:

    Feature 2.x module 3.x equivalent
    Document scanning (Automatic & manual scanning) Verifai or VerifaiLite Verifai and VerifaiCommons
    Document scanning + NFC scanning Verifai Verifai and VerifaiCommons + VerifaiNFC
    Document scanning + Liveness check Verifai or VerifaiLite Verifai and VerifaiCommons + VerifaiLiveness
    Document scanning + NFC scanning + Liveness check Verifai Verifai and VerifaiCommons + VerifaiNFC + VerifaiLiveness
    Document scanning + VIZ check Verifai or VerifaiLite Will be supported in a future release
    Document scanning + Security checks Verifai or VerifaiLite Will be supported in a future release

    Manual integration

    If you previously loaded either the Verifai.framework or VerifaiLite.framework modules into your app you'll need to download the new files from the Verifai Dashboard. Once downloaded you'll have to add and link each framework in the same way it was done with the 2.x version of Verifai. Like stated above in the dependencies section, you can remove the Sentry and TesseractOCR dependencies from your project.

    Cocoapods

    If you're using Cocoapods you'll have to update your Podfile to load the new versions of the framework. Because each module is now separate they all have to be loaded separately.

    Feature 2.x Podfile 3.x equivalent
    Document scanning (Automatic & manual scanning) pod 'Verifai', '~> 2.0' or pod 'VerifaiLite', '~> 2.0' pod 'Verifai', '~> 3.3'
    Document scanning + NFC scanning pod 'Verifai', '~> 2.0' pod 'Verifai', '~> 3.3' + pod 'VerifaiNFC', '~> 3.3
    Document scanning + Liveness check pod 'Verifai', '~> 2.0' or pod 'VerifaiLite', '~> 2.0' pod 'Verifai', '~> 3.3' + pod 'VerifaiLiveness', '~> 3.3
    Document scanning + NFC scanning + Liveness check pod 'Verifai', '~> 2.0' pod 'Verifai', '~> 3.3' + pod 'VerifaiNFC', '~> 3.3 + pod 'VerifaiLiveness', '~> 3.3
    Document scanning + VIZ check pod 'Verifai', '~> 2.0' or pod 'VerifaiLite', '~> 2.0' pod 'Verifai', '~> 3.3' + pod 'VerifaiManualDocumentCrosscheck', '~> 3.3
    Document scanning + Security checks pod 'Verifai', '~> 2.0' or pod 'VerifaiLite', '~> 2.0' pod 'Verifai', '~> 3.3' + pod 'VerifaiManualSecurityFeatureCheck', '~> 3.3

    Carthage

    If you're using Carthage you'll have to update your Cartfile to load the new versions of the framework. Because each module is now separate they all have to be loaded separately. Place the following lines in your Cartfile

    Theming

    Theming has been rebuilt from the ground up to allow more precise color setup for each screen. For detailed information on how you can setup the colors for the SDK check out our styling and theming guide.

    Examples

    Licence setup

    Licence setup in Verifai 2.x

    if let bundleIdentifier = Bundle.main.bundleIdentifier {
        Verifai.configure(licence: licenceString,
                          identifier: bundleIdentifier)
                        .success({ (_) in
                            // The operation succeeded
                        })
                        .error({ (error) in
                            // An error occurred
                        })
        }
    }
    

    Licence setup in Verifai 3.x

    // Further on, i.e. application:didFinishLaunchingWithOptions:
    let licenceString = "=== Verifai Licence file V2 ===[...]"
    // Set the licence in the commons
    switch VerifaiCommons.setLicence(licenceString) {
        case .success(_): 
            print("Successfully configured Verifai")
        case .failure(let error): 
            print("🚫 Licence error: \(error)")
    }
    

    Please consult the code example on the right for an example on how licences used to be called in 3.x compared to how they are called in 2.x

    Starting Verifai

    Starting Verifai in 2.x

    /// Handle the tapping of the automatic scan button
    @IBAction func handleAutomaticScanButton() {
        Verifai.scanViewController(scanMode: .ai) { (autoScanVC) in
            // Present the scan VC
            autoScanVC.title = "Scan"
            self.navigationController?.pushViewController(autoScanVC,
                                                          animated: true)
            }
            .error { (error) in
                // An error occurred
                print("Error: \(error.description)")
            }
            .success { (data) in
                // Handle the response from Verifai
                if let response = data {
                    // Verifai detected a document!
                    print("Front image details: \(response.frontImage)")
                }
            }
    }
    

    Starting Verifai in 3.x

    do {
        try Verifai.start(over: self) { result in
            switch result {
            case .failure(let err): 
                print("Error: \(err)")
            case .success(let result):
                // Continue with the result
                let frontImage = result.frontImage
                // etc....
            }
        }
    } catch {
        print("🚫 Licence error: \(error)")
    }
    

    Please consult the code example on the right for an example on how Verifai is started in 3.x compared to how it's started in 2.x

    Starting Verifai NFC

    Starting NFC in 2.x

            // Start the NFC process
            VerifaiNFC.readNfc(documentData: documentData,
            .error({ (error) in
                if let message = error as? VerifaiNFCError {
                    if message.nfc.connectionFailedBluetooth || message.nfc.connectionFailed {
                        state = .notConnected
                    } else {
                        state = .failed
                    }
                }
            })
            .info({ (info) in
                if let message = info as? VerifaiNFCInfo,
                    message.nfc.connected {
                    state = .preparingScan
                }
            })
            .progress({ (progress) in
                state = .scanning
                progress = Float(progress) / Float(100)
            })
            .success({ (data) in
                state = .success
                // Process response
                print("Did the scan complete?: \(data.scanCompleted)")
            })
    

    Starting NFC in 3.x

    // Use result obtained earlier with `Verifai.start`
    let result: VerifaiResult
    do {
        try VerifaiNFC.start(over: self, documentData: result, retrieveImage: true) { nfcResult in
            switch nfcResult {
            case .failure(_): 
                print("Error")
            case .success(let result):
                // Continue with result
                let photo = nfcData.photo
                // etc....
            }
        }
    } catch {
        print("🚫 Licence error: \(error)")
    }
    

    Please consult the code example on the right for an example on how Verifai NFC is started in 3.x compared to how it's started in 2.x

    Starting Verifai Liveness check

    Starting Liveness check in 2.x

    private func startLifenessCheck() {
            Verifai.startLifenessCheck(locale: Locale.current) { (lifenessCheckVC) in
                // Present the view
                self.navigationController?.pushViewController(lifenessCheckVC, animated: true)
            }
            .success { (lifenessCheckResponse) in
                // Handle the response
            }
            .error { (error) in
                // Handle the error
            }
    }
    

    Starting Liveness check in 3.x

    do {
        try VerifaiLiveness.start(over: self) { (result) in
            switch result {
            case .failure(_): 
            print("Error")
            case .success(let result):
                // Continue with result
                let checksPassed = result.automaticChecksPassed
                // etc....
            }
        }
    } catch {
        print("🚫 Licence error: \(error)")
    }
    

    Please consult the code example on the right for an example on how Verifai Liveness check is started in 3.x compared to how it's started in 2.x

    Starting Verifai Manual data crosscheck

    Starting Manual data crosscheck in 2.x

    // Make sure we have the necessary data
    guard var documentData = verifaiResponse else {
        return
    }
    // We have a preference for the nfc mrz data but otherwise use the scan mrz data
    if let verifiedMrzData = nfcData?.validatedDocumentData {
        documentData.mrzModel = verifiedMrzData
    }
    // Start the VIZ check
    Verifai.startVizCheck(documentData: documentData,
                          nfcImage: self.nfcData?.documentImage,
                          present: { (vizViewController) in
                            vizViewController.title = "VIZ check"
                            self.navigationController?.pushViewController(vizViewController,
                                                                          animated: true)
    
    })
    // Handle the success
    .success { (data) in
        if let response = data {
            // Return to this screen
            self.navigationController?.popToViewController(self, animated: true)
            // Parse results
            print("Passed all tests? \(data.passedAll)")
        }
    }
    // Handle any errors
    .error { (error) in
        DispatchQueue.main.async {
            self.navigationController?.popToViewController(self, animated: true)
            // An error ocurred
            print("Error: \(error.description)")
        }
    }
    

    Starting Manual data crosscheck in 3.x

    // Use result obtained earlier with `Verifai.start`
    let result: VerifaiResult
    // Optional, adds an extra check if the photo area is unblocked
    let nfcResult: VerifaiNFCResult? 
    do {
        try VerifaiManualDataCrosscheck.start(over: self,
                                              documentData: result,
                                              nfcImage: nfcResult?.photo) { mdcsResult in
                                                // Handle result
                                                switch mdcsResult {
                                                case .success(let checkResult):
                                                    // Continue with result
                                                    let allChecksPassed = checkResult.passedAll
                                                    // etc....
                                                case .failure(let error):
                                                    print("Error: \(error)")
                                                }
        }
    } catch {
        print("🚫 Licence error: \(error)")
    }
    

    Please consult the code example on the right for an example on how Verifai Manual data crosscheck is started in 3.x compared to how it's started in 2.x

    Starting Verifai Manual security feature check

    Starting Manual security feature check in 2.x

    let response: VerifaiResponse = someResponse // The response that was obtained earlier by a scan
    
    // Start the security feature flow
    Verifai.securityFeatureViewController(for: response) { (securityFeaturesVC) in
        // Push the given ViewController on the navigation stack
        self.navigationController?.pushViewController(securityFeaturesVC, animated: true)
    }
    // Handle any error
    .error { (error) in
        print("🚫 Error occured while starting security features: \(error)")
    }
    // Handle success
    .success { (securityFeatureResponse) in
        // Return to the viewController that pushed the security feature flow
        self.navigationController?.popToViewController(self, animated: true)
    
        guard let securityFeatureResponse = securityFeatureResponse else { return }
    
        print("Passed security feature check? \(securityFeatureResponse.passed)")
    }
    

    Starting Manual security feature check in 3.x

    // Use result obtained earlier with `Verifai.start`
    let result: VerifaiResult
    do {
        try VerifaiManualSecurityFeatureCheck.start(over: self, documentData: result) { result in
            switch result {
            case .failure(let error):
                print("Error: \(error)")
            case .success(let checkResult):
                // Continue with result
                let checksPassed = checkResult.passed
                // etc....
            }
        }
    } catch {
        print("🚫 Licence error: \(error)")
    }
    

    Please consult the code example on the right for an example on how Verifai Manual security feature check is started in 3.x compared to how it's started in 2.x