Skip to main content
Skip table of contents

VFace Android Quickstart Sample App

Get started by running the VFace Sample App and review its code alongside the Android integration guide. Code can be repurposed for your own application.

Sample App (sample-vface)

The VFace sample-vface app demonstrates Veridium SDK integration and use of VFace. It is intended as a minimal functional example and demonstrates:

  • Licensing

  • SDK initialisation

  • Enrolment and authentication

  • Match and storage customisation

  • Image import / export


If your licence is only valid for VFace it will only function with the sample-vface app, not any other Veridium sample app.

Please remove all previous versions of the sample apps before installing updated versions. These apps require a minimum of Android API 21 (Android 5.0, Lollipop).

This guide does not cover using the emulator due to use of hardware cameras.

Build and Run

To build and run the sample-vface app

  1. Download and extract the VeridiumSDK_Android_[version].zip package as provided by your Veridium representative. The sample-vface app is located at the root.

  2. In Android Studio got to File->Open and open the root directory of the Veridium SDK package. If Android studio requests that you install the required Android SDK Platforms and Tools, do so.

  3. In the project tab, in the left side navigation window, select Android from the dropdown view options. You will see all the available sample apps and gradle scripts, including sample-vface.

  4. In the run configurations dropdown in the toolbar, select

  5. Clean the project by menu selecting Build->Clean and then build the app via Build->Rebuild. This should successfully build the application.

  6. A licence string is required, provided by your Veridium representative. This is an online licence and requires the device to have internet access. Unzip the licence package and open sdk.lic with a text editor [Note: the file is UTF-8 plain text encoded]. Copy the whole licence string.

  7. In Android Studio, under Gradle Scripts in the left pane navigation, open build.gradle (Module:sample-vface:app) and paste the string to replace <licence> at

    // TODO add here the VERIDIUM SDK licence
    manifestPlaceholders = [VERIDIUM_SDK_LICENSE: "<licence>"]
  8. Your licence is tied to the app's applicationId. If required, change the applicationId in the build.gradle to that indicated by your Veridium salesperson. As supplied, the ID is set as applicationId "com.veridiumid.sample.vface".

  9. Connect an Android device via USB. Ensure the device has USB debugging enabled within Developer Options. Select the device from the available devices dropdown on the toolbar. [Note: the method of accessing Developer Options varies between devices. Please consult documentation from the manufacturer]

  10. Uninstall older versions of the app from the device.

  11. Hit the run toolbar button to launch the app on the device. On first operation the app will ask for permissions. Press Allow or the app will not function.

App Features

The app has two java source files, a manifest, and a basic home screen layout. CustomVFaceActivity extends VFaceBiometricsActivity and is used to override core behaviour. This activity will be launched by the Veridium SDK during VFace operations.

CustomVFaceActivity uses the default storage where templates are stored locally on the device:

protected IKVStore openStorage() {
    return DataStorage.getDefaultStorage();

Note the important entry in AndroidManifest.xml configuring CustomVFaceActivity as the VFace activity via com.veridiumid.sdk.component.config meta-data, and portrait only mode:


MainActvity initialises the Veridium SDK and sets up buttons for enrolment and authentication. A generic ActivityResultLauncher, VFaceLauncher, is created to launch VFace operations, and a BiometricResultsParser used to receive the result.

enrolWithPermission and authWithPermission objects make use of RequestPermission()to ask for user permissions. On success, VFace is configured and an intent create for launch. VFaceLauncher is then called to run the operation defined by the intent.

NOTE: The Veridium SDK will itself ask for the appropriate permissions from the user if not yet allowed.

Examples are given for these specific use cases:

  • SDK Initialisation, see MainActivity -> private void initSDK()

  • Generating VFace templates from images, see MainActivity -> private byte[] templateFromImage()

  • Image export, see CustomVFaceActivity -> protected boolean doExport()

  • Accessing authentication templates, see CustomVFaceActivity -> protected boolean matchAuthentication(BiometricsResult<?> result). As supplied, this feature is commented out.


License Troubleshooting

  • The provided licence is for specific features. Ensure you are running the correct app, sample-vface.

  • Ensure your licence copied correctly without introducing new lines. Your text editor should open the the licence file as UTF-8.

  • Double check the applicatonid matches that indicated by your Veridium salesperson.

  • Ensure the device has internet access.

  • Uninstall the app, clean, build, and re-install.

  • In Android Studio, open Logcat in the bottom pane. Ensure the correct device is selected and filter by package:mine. Copy the whole contents of Logcat following app start, and send it to your Veridium rep.

  • Screenshot where you're entering the licence and send to your Veridium salesperson.

  • We are always happy to take a call to resolve sample app build issues.

Other Issues

  • In Android Studio, if updating from a previous SDK version, you may need to clean the caches via File->Invalidate caches...

  • If your device does not show, disconnect it, go to developer options and select Revoke USB debugging authorisations. Reconnect the device and it should prompt to Allow USB debugging.

  • In case of the error Error:Execution failed for task ':sample-vface:mergeDebugResources this is typically caused by the directory path to the project being too long. Reduce the length of the folder names.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.