NAV Navbar
kotlin
  • Upgrade guide Android SDK 2.x to 3.x
  • Upgrade guide Android SDK 2.x to 3.x

    Verifai 3.0 for Android makes it easier than ever to scan documents. This latest version lets the user do more with even less code for the developer to write.

    Removed methods

    Verifai version 3.0 manages its own initialization. Therefor the Verifai.downloadNeuralModel(...), Verifai.downloadDocuments(...) and Verifai.downloadCountryCodes(...) became obsolete and are not needed anymore.

    There is also no difference anymore between the "automatic" and "manual" modes. The new Verifai SDK contains new mechanisms that automatically decides the route the user takes through the SDK. Delivering the best result possible.

    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.0 equivalent
    Configure Verifai with a licence Verifai.configure(licence:identifier:) Verifai.setLicence(licence:)
    Automatic scan Verifai.scanViewController(scanMode: .ai) Verifai.start(...)
    Manual scan Verifai.scanViewController(scanMode: .manual) Verifai.start(...)

    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 online models Verifai.downloadNeuralModel()
    Load online OCR models Verifai.downloadOcrMrzNeuralModels()
    Check if AI mode is supported Verifai.isAiModeSupported
    Cancel the downloads Verifai.cancelNeuralModelDownload()
    Load local model Verifai.setNeuralModel
    Get the available document country codes Verifai.downloadCountryCodes()
    Prefetch documents Verifai.downloadDocuments()

    New dependency structure

    The older versions of Verifai became larger and larger with every SDK update because a lot of new features have been added. However, not all implementations need to make use of all the features that Verifai offers. This is why Version 3.0 introduces seperate modules. These modules can easily be added to the app's Gradle files. Verifai has been split up in the following modules:

    Module name What is does
    Core Contains the main SDK needs like the flows and user interface components
    NFC Contains everything to read a supported documents NFC-chip
    Liveness Contains the Liveness checks

    This new setup makes the SDK, and thereby the app that implements it, smaller when not need all of Verifais features are needed. Even more space will be saved when deploying the app as an Android App Bundle .aab.

    Licence and configuration

    Licence setup in Verifai 2.x

    // Old code (do not use)
    
    Verifai.configure("your_licence", "your_identifier", object : VerifaiLicenceListener {
        override fun onConfigured() {
            // Handle success
            // Verifai can now be started
        }
    
        override fun onError(e: LicenceNotValidException) {
            // Handle error
        }
    })
    

    Licence setup in Verifai 3.x

    Verifai.setLicence(licenceString)
    
    // Config starts here. The config is optional, so are all the parameters of this method.
    val config = VerifaiConfiguration(
        enable_automatic = true
    )
    Verifai.configure(config)
    
    

    A valid Verifai licence is needed to use Verifai SDK. Version 3.0 handles the initialization a bit different then previous versions. An example can be found underneath.

    Starting Verifai

    Starting Verifai in 2.x

    // Old code (do not use)
    
    Verifai.start(this, VerifaiScanMode.AI, object : VerifaiResultListener {
            override fun onResult(result: VerifaiResult) {
                // Handle result
                showResultActivity(result)
            }
    
            override fun onUpdateAvailable() {
                // This will be called when there is a new version of the SDK available. The scanning will continue.
                // You could log to your central logging to be notified of outdated version.
            }
    
            override fun onError(e: Throwable) {
                // Handle errors
                when (e) {
                    is FatalException -> {
                        // Verifai can not start
                    }
                    is CriticalException -> {
                        // AI mode will not work. It is possible to start the Manual mode.
                        auto_button.isEnabled = false
                    }
                    else -> {
                        // Network problems during scanning
                    }
                }
            }
        })
    

    Starting Verifai in 3.x

        Verifai.startScan(this, object : VerifaiResultListener {
            override fun onSuccess(result: VerifaiResult) {
                // Handle the result. Please consult the general docs for more information regarding the result object and its contents.
            }
    
            override fun onCanceled() {
                // What to do when the user cancels the SDK route. This will mostly be triggered because of the user pressing the back button or locking the phone in certain states. The user can restart Verifai from the start. No errors occured.
            }
    
            override fun onError(e: Throwable) {
                if (e is LicenceNotValidException) {
                        // The licence is not working. Please get the correct licence from the dashboard.
                    Log.d("Authentication", "Authentication failed")
                }
            }
        })
    

    It is possible to start Verifai after setting the licence and the optional config. Verifai uses a listener to notify you when Verifai succeeds, fails or has been cancelled. Starting Verifai has been changed slightly.

    Verifai will not notify anymore when there are newer neural networks available. Verifai now manages and updates all of its components. The onUpdateAvailable() call out of the Verifai 2.x listener has been replaced by onCanceled(). This method will be called when the user cancels Verifai. This can be triggered by pressing the back button.

    NFC

    Starting NFC in 2.x

    // Old code (do not use)
    
    Verifai.readNfc(
                    activity!!,
                    verifaiResult,
                    resultListener = object : VerifaiNfcResultListener {
                        override fun onProgress(progress: Int) {
                            // from 0 to 100
                        }
    
                        override fun onResult(result: VerifaiNfcResult) {
                            ScanResultActivity.nfcResult = result
                            showResult(result)
                        }
    
                        override fun onError(e: Throwable) {
                            if (e is NfcDisabledException) {
                                // Show enable nfc dialog
                                activity?.runOnUiThread {
                                    if (!activity!!.isFinishing) {
                                        AlertDialog.Builder(activity!!)
                                                .setTitle("NFC Disabled")
                                                .setMessage("Please enable NFC.")
                                                .setCancelable(false)
                                                .setPositiveButton(android.R.string.ok) { dialog, which ->
                                                    // ok
                                                }.show()
                                    }
                                }
                            } else if (e is NoNfcException) {
                                // Show enable nfc dialog
                                activity?.runOnUiThread {
                                    if (!activity!!.isFinishing) {
                                        AlertDialog.Builder(activity!!)
                                                .setTitle("No NFC support")
                                                .setMessage("This device does not support NFC.")
                                                .setCancelable(false)
                                                .setPositiveButton(android.R.string.ok) { dialog, which ->
                                                    // ok
                                                }.show()
                                    }
                                }
                            }
    
                            Verifai.logger?.log(e)
                        }
                    })
    

    Starting NFC in 3.x

    val nfcListener = object : VerifaiNfcResultListener {
        override fun onResult(result: VerifaiNfcResult) {
            Verifai.logger?.log("NFC Completed")
        }
    
        override fun onProgress(progress: Int) {
            // Optional to implement
        }
    
        override fun onError(e: Throwable) {
            e.printStackTrace()
        }
    }
    
    VerifaiNfc.start(this, verifaiCoreResult, true, nfcListener)
    

    The NFC component of Verifai has been split up into a different module. This results in less dependencies and a smaller library size for apps that do not need this module.

    This change results that the readNfc method is not available in the Verifai package anymore.

    The Verifai.readNfc has been renamed to VerifaiNfc.start(). Apart from the split and a revamped UI, nothing much has changed.

    Liveness check

    Starting Liveness check in 2.x

    // Old code (do not use)
    
    Verifai.startLifenessCheck(
        this,
        object : VerifaiLifenessCheckListener {
                override fun onResult(result: VerifaiLifenessCheckResult) {
                    // Handle result
                    result.lifenessChecks?.forEach { check ->
                        Log.d("LifenessCheck", "${check.javaClass}: ${check.status}")
                    }
                }
    
                override fun onError(e: Throwable) {
                    // Handle error
                    when (e) {
                        is LifenessChecksNotAvailableException ->
                           // Lifeness check is not available on your device
                        is RecordPermissionException ->
                           // Missing record microphone permission
                        is CameraPermissionException ->
                           // Missing camera permission
                        is InvalidLifenessCheckException ->
                           // Invalid check (for example when the user has to tilt their head 0 degrees (do nothing)
                        is TimeoutException ->
                            // The check was not completed in 60 seconds
                        is LicenceNotValidException ->
                            // Invalid licence          
                        else ->
                            // Some unexpected error
                    }
                }
            }
    )
    

    Starting Liveness check in 3.x

    VerifaiLiveness.start(this, null, object : VerifaiLivenessCheckListener {
        override fun onResult(results: com.verifai.liveness.result.VerifaiLivenessCheckResults) {
            Log.d("results", "done")
        }
    
        override fun onError(e: Throwable) {
            e.printStackTrace()
        }
    })
    

    Please also note, we changed the spelling of this module to liveness check because it checks if the input stream is live, not if the person is alive (life).

    Handling the result

    In previous versions of Verifai the country field was nullable / optional, but since Verifai 3.0 the field is always populated if the model information is set.