NAV Navbar
  • Quick start
  • Detailed documentation
  • Quick start

    In the quick start implementation guide we describe the fastest way to implement our SDK.

    This is the high level process: 1. Add the dependencies with Gradle 2. Obtaining a licence 3. Add some code to your project to start the process 4. Add some permissions to your AndroidManifest.xml

    When you have done that, the verifai software is integrated into your very own app.

    Obtaining a licence

    Verifai only works with a valid licence. Obtaining a Verifai licence is the same for all platforms. The licence can be found in the Verifai dashboard. Need more information? Please read the guide in the general docs.

    The Android SDK uses the package name that has been declared in your apps Manifest.xml file as the licence identifier. Please make sure that this identifier has been added to your licence. An incorrect licence will result in a LicenceNotValidException.

    Add dependencies via Gradle

    The distribution of the SDK and its components is done via a Maven webservice. This should be the easiest way to integrate. Please copy paste from the code example:

    implementation 'com.verifai:core:3.1.0'
    implementation 'com.verifai:nfc:3.1.0'
    implementation 'com.verifai:liveness-check:3.1.0'
    implementation 'com.verifai:manual-data-crosscheck:3.1.0'
    implementation 'com.verifai:manual-security-features-check:3.1.0'
    

    However, this package can only be found when Verifai's maven repository has been added to the project's Build.gradle file:

    allprojects {
        repositories {
            google()
            jcenter()
            maven { url = 'https://dashboard.verifai.com/downloads/sdk/maven/' }
        }
    }
    

    Add the code

    Verifai can be configured and started with just a few lines of code. The boilerplate code for implementing Verifai is as stated here.

    Verifai.setLicence(licenceString) // The licence string that has been obtained from the dashboard.
    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")
            }
        }
    })
    
    String licence = "=== Verifai Licence file V2 ===\n" +
    Verifai.setLicence(this, licence); // The licence string that has been obtained from the dashboard.
    
    VerifaiResultListener resultListener = new VerifaiResultListener() {
        @Override
        public void 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
        public void onSuccess(VerifaiResult verifaiResult) {
            // Handle the result. Please consult the general docs for more information regarding the result object and its contents.
        }
    
        @Override
        public void onError(@NotNull Throwable throwable) {
            Log.d("error", throwable.getMessage());
        }
    };
    Verifai.startScan(this, resultListener);
    

    Configuration options can be added. More detailed information about this can be found over here.

    The Verifai Android SDK example code on GitHub might help while implementing the SDK. The example code can be found over here.

    Add permissions

    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.hardware.camera.autofocus" />
    

    Verifai needs an internet connection and a camera to work. These features rely on permissions. Therefore the following permissions should be declard in the AndroidManifest.xml file of your app.

    Why are the permissions needed

    Verifai has been built with privacy in mind. This is why Verifai wants to be clear about the permissions it uses. This paragraph explains why the permissions are needed. Please point any questions regarding privacy towards our support team.

    The internet permission

    The internet permission is needed so the Verifai SDK can download advanced neural networks to recognize and read documents. The permission is also needed to let the user pick between documents since these documents and comming from Verifai's databases.

    The camera permission

    Verifai uses the device's camera to recognize, and read from, documents. The cameras are the eyes of the device. To prevent developers from spying on users they need to ask permission from user via the Android system. The user will see a modal with the question if the camera may be used.

    The autofocus permission

    Verifai uses intelligence autofocus to capture the documents as clear as possible. The app needs to have the autofocus permission stated in its manifest file to guarantee clear and readable images.

    Reading the NFC chip

    Doing the liveness check

    Processing the results

    Link to Core processing Link to NFC processing Link to Liveness processing

    Detailed documentation

    If your use case or environment is a little more complicated you can use the the this more in detail part of the documentation. For most situations however the Quick start would be sufficient.

    Manual installation of components

    It is possible to install Verifai manually. Taking this route is not the preffered route that Verifai offers, but it is sometimes undenieable. Please take the following steps to manually add the Verifai packages.

    1. Add the dependencies that Verifai uses

    Verifai is distributed via .AAR modules. Android uses these type of modules to import third party source in your app. The downside of this kind of packaging is that dependencies that the dependency its depenencies are not packaged with it. So these have to be added manually.

    1.1 Verifai Core dependencies

    Please Add the following dependencies to your projects build.gradle. These dependencies are needed for all of Verifai's modules.

    implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.41"
    
    implementation 'com.android.support:recyclerview-v7:28.0.0'
    implementation "com.android.support:support-v4:28.0.0"
    implementation "com.android.support:design:28.0.0"
    implementation "com.android.support:multidex:1.0.3"
    
    implementation "android.arch.lifecycle:viewmodel:1.1.1"
    implementation "android.arch.lifecycle:livedata:1.1.1"
    implementation "android.arch.lifecycle:extensions:1.1.1"
    
    implementation "com.google.code.gson:gson:2.8.2"
    implementation "io.gsonfire:gson-fire:$json_fire_version"
    
    implementation "io.reactivex.rxjava2:rxjava:2.1.1"
    implementation "io.reactivex.rxjava2:rxandroid:2.1.1"
    
    implementation "org.tensorflow:tensorflow-android:1.12.0"
    
    implementation "com.squareup.retrofit2:retrofit:2.3.0"
    implementation "com.squareup.retrofit2:converter-scalars:2.3.0"
    implementation "com.squareup.retrofit2:converter-gson:2.3.0"
    implementation "com.squareup.retrofit2:adapter-rxjava2:2.3.0"
    
    implementation "io.swagger:swagger-annotations:1.5.15"
    implementation("org.apache.oltu.oauth2:org.apache.oltu.oauth2.client:1.0.1") {
        exclude group: 'org.apache.oltu.oauth2', module: 'org.apache.oltu.oauth2.common'
    }
    
    implementation "org.threeten:threetenbp:1.3.5"
    
    implementation group: 'commons-lang', name: 'commons-lang', version: '2.6'
    implementation group: 'org.apache.commons', name: 'commons-math3', version: '3.6.1'
    implementation group: 'org.apache.commons', name: 'commons-io', version: '1.3.2'
    
    compileOnly "javax.annotation:jsr250-api:1.0"
    
    implementation "com.verifai:opencv:4.0.0"
    

    1.2 NFC dependency

    Add the following depedency when you are planning to use Verifai's NFC component.

    api 'com.madgag.spongycastle:prov:1.58.0.0'
    

    1.3 Liveness dependency

    Add the following dependencies when you are planning to use Verifai's Liveness component.

    implementation "com.google.android.gms:play-services-vision:17.0.2"
    implementation 'com.googlecode.mp4parser:isoparser:1.1.22'
    

    2. Download the Verifai modules

    Please use your Verifai account to download the Verifai module (library) files from the dashboard. The downloads can be found over here:

    https://dashboard.verifai.com/downloads/sdk/

    3. Import the Verifai files

    Please follow the Android documentation on importing modules. These modules are the .AAR files that have been downloaded in the previous step. The Android documentation concerning the import of modules can be found over here:

    https://developer.android.com/studio/projects/add-app-module#ImportAModule

    Please repeat this step for every downloaded module. Do not forget to add the importet modules to your app's Gradle file.

    implementation (project(":THE_NAME_YOU_GAVE_THE_MODULE_AT_IMPORTING")) {
        transitive=true
    }
    

    Styling and theming

    It is possible to change Verifai's colors to match your app's styling. All colors have been defined in Verifai's resource files and can be overwritten. Please consult Styling and theming in the general docs to find the color that needs to be overwritten.

    All the Verifai color names have been prefixed with Verifai on Android. This to prevent collisions between color names in multiple resource files. So BottomBoxBackgroundColor will be VerifaiBottomBoxBackgroundColor on Android. These renewed color definitions will go in your apps res/values/colors.xml file like this:

    <?xml version="1.0" encoding="utf-8"?>
    <resources>
        <color name="colorPrimary">#FF576D</color>
        <color name="backgroundColor">#FFFFFF</color>
    
        <color name="VerifaiBottomBoxBackgroundColor">Your color. E.g. #000000</color>
    </resources>
    

    ProGuard and code optimisation

    Verifai 3.0 is fully compatible with ProGuard and Google's latest R8 compiler. Bringing even more privacy, security and code optimizations to all ProGuard enabled app builds. All that is needed is to add the following code to your app's Build.gradle file.

    shrinkResources true
    minifyEnabled true
    

    Verifai has already been shrunk and obfuscated on build time. So please exclude these from getting obfuscated again. This can be done by adding the following lines to your proguard file:

    -keep class com.verifai.core.** { *; }
    -keep class com.verifai.nfc.** { *; }
    -keep class com.verifai.liveness.** { *; }
    

    It is recommended to ship you app as an Android App Bundle (aab). Aab's give Google Play the possibility to distribute apps for specific hardware architectures and screen sizes. Resulting in smaller installation sizes because the end user will only receive the resources that are needed to run the app on its specific hardware.

    Attaching a logger

    Verifai.logger = object : VerifaiLogger {
    
        private val tag = javaClass.simpleName
    
        override fun log(e: Throwable) {
            Log.e(tag, Log.getStackTraceString(e))
            Sentry.capture(e) // Example when using Sentry, can basically be anything.
        }
    
        override fun log(event: String) {
            Log.i(tag, event)
            Sentry.capture(event). // Example when using Sentry, can basically be anything.
        }
    }
    
    Verifai.logger = new VerifaiLogger() {
        @Override
        public void log(@NotNull Throwable throwable) {
    
        }
    
        @Override
        public void log(@NotNull String s) {
    
        }
    };
    

    ⚠️ NOTE: this is for debugging purposes only. You can attach a VerifaiLogger to the Verifai Core module to read the log output from all the different Verifai modules.

    Feature configuration options

    Verifai contains multiple configuration options. The options can fit Verifai in any use-case. The navigation through the SDK screens differ when using different options.

    The configuration can be set by calling Verifai.configure(..) between setting the licence and starting Verifai.

    Verifai.setLicence(licenceString)
    
    // Config starts here
    val config = VerifaiConfiguration(
        enable_automatic = true,
        require_document_copy = true,
        enable_post_cropping = true,
        enable_manual = true,
        enable_auto_updated = true,
        require_mrz_contents = true,
        require_nfc_when_available = true,
        read_mrz_contents = true
    )
    Verifai.configure(config)
    // Config ends here
    
    Verifai.start(....)
    
    Verifai.setLicence(licenceString)
    
    VerifaiConfiguration configuration = new VerifaiConfiguration();
    configuration.setScanDuration(5.0);
    Verifai.configure(configuration);
    // Config ends here
    
    Verifai.start(....)
    
    Module name What is does Object type Default value
    enable_automatic determines if we use the “route 1” or classifier Boolean true
    require_document_copy if set to false it switches off all AI mode screens and picture correction screens. Also skips taking a picture of the non-MRZ side. Boolean true
    enable_post_cropping The user can manually adjust the proposed document crop wheen set to true. Boolean true
    enable_manual_masking The user can only scan documents that are know in Verifai's databases. Boolean true
    enable_auto_updated Verifai does check for updates on it's artificial intelligence models and updates when available. This improves Verifai overtime. Boolean true
    require_mrz_contents Boolean true
    require_nfc_when_available if set to true, the NfcKeyWhenAvailableValidator is added and if there are several results in J1 that contain different chips, it should be shown. If all the same it can be skipped. Boolean false
    read_mrz_contents if set true the whole MRZ will be read, if false it only reads the prefix Boolean true
    scanDuration Double 5.0
    extraValidators A list of validators. Please check the paragraph called "validators" List<VerifaiValidatorInterface> emptyList()

    Validators

    Validators can take the Verifai SDK onto a whole new level of customization. Enhancing the general configuration options to create the perfect fit for your use case. Validators can for example black- or whitelist certain countries, exclude document types, allow only documenet with certain zones etcetera, etcetera.

    Verifai comes with a couple of standard validators.

    Validator class Purpose
    VerifaiDocumentCountryBlacklistValidator Make documents from certain countries unavailable
    VerifaiDocumentCountryWhitelistValidator Make only the documents of the countries on the list available.
    VerifaiDocumentHasMrzValidator Only allows documents with a Machine Readable Zone (MRZ) to be scanned.
    VerifaiDocumentIsDrivingLicenceValidator Only allows driving licences to be scanned.
    VerifaiDocumentIsTravelDocumentValidator Only allows travel documents to be scanned. These are passports and identity cards.
    VerifaiDocumentTypesValidator Only allows documents from the given documentType.
    VerifaiDocumentValidatorInterface
    VerifaiMrzAvailableValidator
    VerifaiMrzCorrectValidator Forces the MRZ to be correct.
    VerifaiNfcKeyRequiredValidator
    VerifaiRequireNfcWhenAvailableValidator Required the NFC key to be correct when the document contains a supported NFC-chip.

    Errors

    What follows is an overview of the errors Verifai can return with a description of what causes them.

    Core Errors - Possible in all Verifai modules

    Error Type Description Possible solutions
    LicenceNotValidException FatalException The used Verifai licence is invalid. Therefore Verifai can not be run. Retreive a new licence from https://dashboard.verifai.com
    DownloadException `` Something went wrong downloading one of neural networks Make sure an internet connection is active and retry
    NotEnoughMemoryException `` The device is out of memory. Please retry.
    FatalException `` A general fatal exception Try again, please contact Verifai support when stuck.

    NFC Component Specific errors

    Error Type Description Possible solutions
    NfcDisabledException FatalException The device has an NFC chip but it has been disabled. Ask the user to enable NFC.
    NfcException `` General exception Retry. Please contact support when it keeps occuring.
    NoNfcException `` Device has no NFC chip Skip NFC.

    Liveness Component Specific errors

    Error Type Description Possible solutions
    CameraException FatalException The device has an NFC chip but it has been disabled. Ask the user to enable NFC.
    CameraPermissionException `` General camera issue exception Retry. Please contact support when it keeps occuring.
    InvalidLivenessCheckException `` Device has no NFC chip Skip NFC.
    LivenessChecksNotAvailableException `` Liveness Checks not available. Google Play services and Android 4.3 or newer are required. Skip Liveness checks.
    RecordPermissionException `` Record permission not granted Ask for audio recording permissions.
    TimeoutException `` User did not finish one of the checks on time Let the user retry or continue, depending on your use case.

    NFC Component

    The Verifai NFC module adds extra steps to your Verifai setup. The NFC modules lets the user scan and verify ICAO compliant ID cards and passports and electronic dutch drivers licences. Verifai's NFC process can be found in a separate package and can be installed via gradle.

    implementation 'com.verifai:nfc:3.1.0'
    

    The NFC module is only available for hardware containing a NFC-chip. Please perform the following steps to make your Verifai setup compatible with the Verfai NFC module.

    Check if the hardware has NFC enabled and if the result that has been obtained from the core module has support for NFC.

    VerifaiNfc.isCapable(context) && result?.document?.nfcType != null && result.mrzData?.isNfcKeyValid == true
    
    VerifaiNfc.isCapable(context) && result.document != null && result.document.nfcType != null && result.mrzData != null && result.mrzData.isNfcKeyValid != null && result.mrzData.isNfcKeyValid
    

    The reading can begin after a positive check. This can be done by piping the VerifaiResult object, the one that has been obtained from the core module's listener, to the NFC module.

    val nfcListener = object : VerifaiNfcResultListener {
        override fun onResult(result: VerifaiNfcResult) {
            // Handle the NFC result.
        }
    
        override fun onProgress(progress: Int) {
    
        }
    
        override fun onError(e: Throwable) {
            // Something went wrong.
        }
    }
    
    VerifaiNfc.start(context, it, true, nfcListener)
    
    VerifaiNfcResultListener nfcResultListener = new VerifaiNfcResultListener() {
        @Override
        public void onResult(@NotNull VerifaiNfcResult verifaiNfcResult) {
            // Handle the NFC result.
        }
    
        @Override
        public void onProgress(int i) {
    
        }
    
        @Override
        public void onError(@NotNull Throwable throwable) {
            // Something went wrong.
        }
    };
    VerifaiNfc.start(context, result, true, nfcResultListener);
    

    And done. The contents of the VerifaiNfcResult object can be found in the general docs, since these are the same on all Verifai NFC compatible platforms.

    Not all documents contain a NFC-chip or are not supported by this version of Verifai (yet). The Verifai team keeps working on covering as much travel and identification documents as possible. If you have any documents that don't work, please contact us.

    Liveness Check Component

    The Liveness Check uses machine learning to determine the pose of the human that is holding the device. This by analyzing the video stream that it retreives the front camera of the device.

    Please add the Liveness Check dependency to you project's Build.gradle file by adding the following line:

    implementation 'com.verifai:liveness-check:3.1.0'
    

    Not all devices can run the Liveness checks. The following prerequisites are needed:

    Please check if the user can run the Liveness check before starting it. This can be done by running the following check:

    if(VerifaiLiveness.isLivenessCheckSupported(context)) {
        // Liveness check is supported
    } else {
        // Sorry, the Liveness check is not supported by this device
    }
    
    if(VerifaiLiveness.isLivenessCheckSupported(context)) {
        // Liveness check is supported
    } else {
        // Sorry, the Liveness check is not supported by this device
    }
    

    When supported, the Liveness Check can be started by implementing the following method:

    VerifaiLiveness.start(context, null, object : VerifaiLivenessCheckListener {
        override fun onResult(result: VerifaiLivenessCheckResult) {
            // Handle the result.
        }
    
        override fun onError(e: Throwable) {
            // An error occured. Sorry about that.
        }
    })
    
    VerifaiLivenessCheckListener livenessResultListener = new VerifaiLivenessCheckListener() {
        @Override
        public void onResult(@NotNull VerifaiLivenessCheckResults verifaiLivenessCheckResults) {
                // Handle the result.
        }
    
        @Override
        public void onError(@NotNull Throwable throwable) {
                // An error occured. Sorry about that.
        }
    };
    
    VerifaiLiveness.start(this, null, livenessResultListener);
    

    Result

    The results are the same across Verifai compatible platforms. Please consult the general documentation.

    Permissions

    Verifai always tries to keep the number of permissions to a minimum. Some modules need extra permission checks. The Verifai Liveness module needs an extra permission to run.

    Microphone

    The user is asked to perform certain physical actions. These can vary from rotating the head to say certain words. All these actions are recorded and rendered into an .mp4 movie. This movie contains the frames contained from the camera and the sound that has been obtained from the user's microphone. The microphone is not needed in other modules and therefore only included in the Liveness module.

    Please add the following permission to your manifest file.

    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    

    Manual Data Crosscheck Component

    Please add the Manual Data Crosscheck dependency to you project's Build.gradle file by adding the following line:

    implementation 'com.verifai:manual-data-crosscheck:3.1.0'
    

    Add the following code to your project. The Manual Data Crosscheck needs the result of a document scan. It can also match the picture obtained from Verifais NFC-module when needed.

    VerifaiManualDataCrossCheck.start(this, theResultObtainedFromTheDocumentScanning, object : VerifaiManualDataCrossCheckListener {
        override fun onResult(result: VerifaiManualDataCrossCheckResult) {
           // This is where you get the result.
        }
    
        override fun onCanceled() {
        }
    
        override fun onError(e: Throwable) {
            // Something went wrong, sorry about that. Please contact support when this keeps occuring.
        }
    })
    

    Result

    Please consult the general documentation since the results are the same on iOS and Android.

    Manual Security Data Check Component

    Please add the Manual Data Crosschec dependency to you project's Build.gradle file by adding the following line:

    implementation 'com.verifai:manual-security-features-check:3.1.0'
    

    Add the following code to your project. The Manual Security Data Check needs the result of a document scan.

    VerifaiManualSecurityFeaturesCheck.start(this, MainActivity.verifaiResult!!, object : VerifaiManualSecurityFeaturesCheckListener {
        override fun onResult(result: VerifaiManualSecurityFeaturesResult) {
            // This is where you get the result.
        }
    
        override fun onCanceled() {
        }
    
        override fun onError(e: Throwable) {
            // Something went wrong, sorry about that. Please contact support when this keeps occuring.
        }
    })
    

    Result

    Please consult the general documentation since the results are the same on iOS and Android.