Netverify & Fastfill SDK offers scanning and authentication of governmental issued IDs.
- Release notes
- Setup
- Dependencies
- Initialization
- Configuration
- Customization
- SDK Workflow
- Custom Scan View
- Callback
For changes in the technical area, please read our transition guide.
SDK version: 2.10.0
- Added Custom UI functionality to implement your own UI design
- Improved extraction of NFC Passports and IDs
- Extract name suffix from US/CAN Driving Licenses
- Improved face capturing
- Improved image quality check to reduce blurred images
- Fixed data extraction for a few US/CAN Driving Licenses
The basic setup is required before continuing with the following setup for Netverify.
Using the SDK requires an activity declaration in your AndroidManifest.xml.
<activity
android:theme="@style/Theme.Netverify"
android:hardwareAccelerated="true"
android:name="com.jumio.nv.NetverifyActivity"
android:configChanges="orientation|screenSize|screenLayout|keyboardHidden"/>
You can specify your own theme (see chapter Customization). The orientation can be sensor based or locked with the attribute android:screenOrientation.
If you are using eMRTD scanning, following lines are needed:
-keep class net.sf.scuba.smartcards.IsoDepCardService {*;}
-keep class org.jmrtd.** { *; }
-keep class net.sf.scuba.** {*;}
-keep class org.spongycastle.** {*;}
-keep class org.ejbca.** {*;}
-dontwarn java.nio.**
-dontwarn org.codehaus.**
-dontwarn org.ejbca.**
-dontwarn org.spongycastle.**
-dontwarn org.jmrtd.PassportService
-dontwarn net.sf.scuba.**
If you want to use offline scanning for Fastfill please contact your Jumio Customer Success Manager.
If an optional module is not linked, the scan method is not available but the library size is reduced. The Sample app apk size with the products Netverify and BAM included is currently 19.91 MB.
| Dependency | Mandatory | Description | Size (Jumio libs only) |
|---|---|---|---|
| com.jumio.android:core:.0@aar | x | Jumio Core library | 3.84 MB |
| com.jumio.android:nv:2.10.0@aar | x | Netverify library | 517.75 KB |
| com.android.support:appcompat-v7:26.1.0 | x | Android native library | - |
| com.android.support:support-v4:26.1.0 | x | Android native library | - |
| com.android.support:cardview-v7:26.1.0 | x | Android cardview library (Netverify only) | - |
| com.google.android.gms:play-services-vision:11.4.0 | x | Barcode Scanning | - |
| com.jumio.android:nv-liveness:2.10.0@aar | x | Face-Liveness library | 4.32 MB |
| com.android.support:design:26.1.0 | Android native library | - | |
| com.jumio.android:javadoc:2.10.0 | Jumio SDK Javadoc | - | |
| com.jumio.android:nv-barcode:2.10.0@aar | US / CAN Barcode Scanning | 3.46 MB | |
| com.jumio.android:nv-barcode-vision:2.10.0@aar | US / CAN Barcode Scanning Alternative (reduced size) | 36.2 KB | |
| com.jumio.android:nv-mrz:2.10.0@aar | MRZ scanning | 2.16 MB | |
| com.jumio.android:nv-nfc:2.10.0@aar | eMRTD Scanning | 884.40 KB | |
| com.madgag.spongycastle:prov:1.58.0.0 | eMRTD Scanning | - | |
| net.sf.scuba:scuba-sc-android:0.0.12 | eMRTD Scanning | - | |
| com.jumio.android:nv-ocr:2.10.0@aar | Template Matcher | 1.57 MB |
If the dependencies com.jumio.android:nv-liveness and com.jumio.android:nv-barcode-vision are both used in the application, the following lines have to be added to the application tag in the AndroidManifest.xml to avoid merge issues (see AndroidManifest.xml in Sample app):
<meta-data
android:name="com.google.android.gms.vision.DEPENDENCIES"
android:value="barcode, face"
tools:replace="android:value"/>
If the Google Mobile Vision API is not operational on a device, the face workflow in Netverify can not be started!
In this case, the SDK will skip the face workflow despite NetverifySDK.requireFaceMatch(true) being set.
The operationality of the Google Mobile Vision API can be checked with the following SDK method (see NetverifyFragment in Sample app):
GoogleVisionStatus NetverifySDK.isMobileVisionOperational(Activity activity, int requestCode);
This method returns an enum GoogleVisionStatus which can have the following 3 values:
- OPERATIONAL: API is up-to-date and can be used
- NOT_OPERATIONAL: API is not available
- DIALOG_PENDING: API is available but an user-resolvable error occured. The system dialog for the resolvable error is displayed (see Google API reference)
In case of DIALOG_PENDING, the requestCode provided in the method above can used to react to the result of the dialog in the method onActivityResult() as follows (see MainActivity in Sample app)):
@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == NetverifyFragment.GOOGLE_VISION_REQUEST_CODE) {
// Handle the system dialog result - try to initialize the SDK again if the error was resolved
}
}
If you use Netverify and BAM Checkout in your app, add the following dependency:
implementation "com.jumio.android:bam:2.10.0@aar"
Applications implementing the SDK shall not run on rooted devices. Use either the below method or a self-devised check to prevent usage of SDK scanning functionality on rooted devices.
NetverifySDK.isRooted(Context context);
Call the method isSupportedPlatform to check if the device platform is supported by the SDK.
NetverifySDK.isSupportedPlatform();
To create an instance for the SDK, perform the following call as soon as your activity is initialized.
private static String YOURAPITOKEN = "";
private static String YOURAPISECRET = "";
NetverifySDK netverifySDK = NetverifySDK.create(yourActivity, YOURAPITOKEN, YOURAPISECRET, JumioDataCenter.US);
Make sure that your customer API token and API secret are correct, specify an instance
of your activity and provide a reference to identify the scans in your reports (max. 100 characters or null). If your customer account is in the EU data center, use JumioDataCenter.EU instead.
Note: Log into your Jumio customer portal, and you can find your customer API token and API secret on the "Settings" page under "API credentials". We strongly recommend you to store credentials outside your app.
By default, the SDK is used in Fastfill mode which means it is limited to data extraction only. No verification of the ID is performed.
Enable ID verification to receive a verification status and verified data positions (see Callback for Netverify). A callback URL can be specified for individual transactions (constraints see chapter Callback URL). Ensure that your customer account is allowed to use this feature.
Note: Not possible for accounts configured as Fastfill only.
netverifySDK.setRequireVerification(true);
netverifySDK.setCallbackUrl("YOURCALLBACKURL");
You can enable Identity Verification during the ID verification for a specific transaction (if it is enabled for your account).
netverifySDK.setRequireFaceMatch(true);
You can specify issuing country (ISO 3166-1 alpha-3 country code), ID type(s) and/or document variant to skip their selection during the scanning process.
Note: Fastfill does not support paper IDs, except German ID cards.
netverifySDK.setPreselectedCountry("AUT");
netverifySDK.setPreselectedDocumentVariant(NVDocumentVariant.PLASTIC);
ArrayList<NVDocumentType> documentTypes = new ArrayList<>();
documentTypes.add(NVDocumentType.PASSPORT);
documentTypes.add(NVDocumentType.DRIVER_LICENSE);
netverifySDK.setPreselectedDocumentTypes(documentTypes);
The merchant scan reference allows you to identify the scan (max. 100 characters).
Note: Must not contain sensitive data like PII (Personally Identifiable Information) or account login.
netverifySDK.setMerchantScanReference("YOURSCANREFERENCE");
Use the following property to identify the scan in your reports (max. 100 characters).
netverifySDK.setMerchantReportingCriteria("YOURREPORTINGCRITERIA");
You can also set a customer identifier (max. 100 characters).
Note: The customer ID must not contain sensitive data like PII (Personally Identifiable Information) or account login.
netverifySDK.setCustomerId("CUSTOMERID");
You can also set an additional information parameter (max. 255 characters).
Note: The additional information must not contain sensitive data like PII (Personally Identifiable Information) or account login.
netverifySDK.setAdditionalInformation("ADDITIONALINFORMATION");
Use setEnableEMRTD to read the NFC chip of an eMRTD.
netverifySDK.setEnableEMRTD (true);
Note: Not available for Fastfill as it is a Netverify feature.
Use the following setting to explicitly send debug information to Jumio.
netverifySDK.setSendDebugInfoToJumio(true);
Note: Only set this property to true if you are asked by Jumio Customer Service.
You receive a list of the current DebugSessionID by using getDebugID. This method can be called either after initializing or before dismissing the SDK.
netverifySDK.getDebugID();
If you want to use Fastfill in offline mode please contact Jumio Customer Service at support@jumio.com or https://support.jumio.com. Once this feature is enabled for your account, you can find your offline token in your Jumio customer portal on the "Settings" page under "API credentials".
netverifySDK.create(rootActivity, YOUROFFLINETOKEN, COUNTRYCODE)
Note: COUNTRYCODE is an optional parameter and can also be passed as null. In this case no country is preselected in the SDK.
Possible countries: ISO 3166-1 alpha-3 country code
Use the nv-barcode-vision library instead of the play-services-vision libary and add the following meta-data tags to your AndroidManifest.xml:
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
<meta-data
android:name="com.google.android.gms.vision.DEPENDENCIES"
android:value="barcode, face"
tools:replace="android:value"/>
In case Fastfill is used (requireVerification=NO), data extraction can be limited to be executed on device only by enabling setDataExtractionOnMobileOnly
netverifySDK.setDataExtractionOnMobileOnly(true);
Use setCameraPosition to configure the default camera (front or back).
netverifySDK.setCameraPosition(JumioCameraPosition.FRONT);
Jumio Surface is a web tool that offers the possibility to apply and visualize, in real-time, all available customization options for Netverify / Fastfill SDK as well as an export feature to import the applied changes straight into your codebase.
The SDK can be customized to fit your application's look and feel by specifying Theme.Netverify as a parent style and overriding attributes within this theme. Click on the element Theme.Netveriy in the manifest while holding Ctrl and Android Studio will display the available attributes of the Theme that can be customized.
To customize the theme at runtime, overwrite the theme that is used for Netverify in the manifest by calling the following property. Use the resource id of a customized theme that uses Theme.Netverify as parent.
netverifySDK.setCustomTheme(CUSTOMTHEME);
Use the initiate method to preload the SDK and avoid the loading spinner after the SDK start.
netverifySDK.initiate(new NetverifyInitiateCallback() {
@Override
public void onNetverifyInitiateSuccess() {
// YOURCODE
}
@Override
public void onNetverifyInitiateError(int errorCode, int errorDetail, String errorMessage, boolean retryPossible) {
// YOURCODE
}
});
To show the SDK, call the respective method below within your activity or fragment.
Activity: netverifySDK.start();
Fragment: startActivityForResult(netverifySDK.getIntent(), NetverifySDK.REQUEST_CODE);
Note: The default request code is 200. To use another code, override the public static variable NetverifySDK.REQUEST_CODE before displaying the SDK.
Implement the standard onActivityResult method in your activity or fragment for successful scans (Activity.RESULT_OK) and user cancellation notifications (Activity.RESULT_CANCELED). Call netverifySDK.destroy() once you received the result.
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
if (requestCode == NetverifySDK.REQUEST_CODE) {
if (resultCode == Activity.RESULT_OK) {
// OBTAIN PARAMETERS HERE
// YOURCODE
} else if (resultCode == Activity.RESULT_CANCELED) {
// String scanReference = data.getStringExtra(NetverifySDK.EXTRA_SCAN_REFERENCE);
// int errorCode = data.getIntExtra(NetverifySDK.EXTRA_ERROR_CODE, 0);
// String errorMessage = data.getStringExtra(NetverifySDK.EXTRA_ERROR_MESSAGE);
// YOURCODE
}
// CLEANUP THE SDK AFTER RECEIVING THE RESULT
// if (netverifySDK != null) {
// netverifySDK.destroy();
// netverifySDK = null;
// }
}
}
Class NetverifyDocumentData:
| Parameter | Type | Max. length | Description |
|---|---|---|---|
| selectedCountry | String | 3 | ISO 3166-1 alpha-3 country code as provided or selected |
| selectedDocumentType | NVDocumentType | PASSPORT, DRIVER_LICENSE, IDENTITY_CARD or VISA as provided or selected | |
| idNumber | String | 100 | Identification number of the document |
| personalNumber | String | 14 | Personal number of the document |
| issuingDate | Date | Date of issue | |
| expiryDate | Date | Date of expiry | |
| issuingCountry | String | 3 | Country of issue as (ISO 3166-1 alpha-3 country code |
| lastName | String | 100 | Last name of the customer |
| firstName | String | 100 | First name of the customer |
| middleName | String | 100 | Middle name of the customer |
| dob | Date | Date of birth | |
| gender | NVGender | Gender M or F | |
| originatingCountry | String | 3 | Country of origin as (ISO 3166-1 alpha-3 country code |
| addressLine | String | 64 | Street name |
| city | String | 64 | City |
| subdivision | String | 3 | Last three characters of ISO 3166-2:US state code |
| postCode | String | 15 | Postal code |
| mrzData | NetverifyMrzData | MRZ data, see table below | |
| optionalData1 | String | 50 | Optional field of MRZ line 1 |
| optionalData2 | String | 50 | Optional field of MRZ line 2 |
| placeOfBirth | String | 255 | Place of Birth |
| extractionMethod | NVExtractionMethod | Extraction method used during scanning (MRZ, OCR, BARCODE, BARCODE_OCR or NONE) | |
| emrtdStatus | EMRTDStatus | Verification status of an eMRTD scan VERIFIED (eMRTD scanned and authenticated), DENIED (eMRTD scanned and not authenticated) or NOT_AVAILABLE (no NFC on device or eMRTD feature disabled), NOT_PERFORMED (NFC disabled on device) |
Class NetverifyMrzData
| Parameter | Type | Max. length | Description |
|---|---|---|---|
| format | NVMRZFormat | ||
| line1 | String | 50 | MRZ line 1 |
| line2 | String | 50 | MRZ line 2 |
| line3 | String | 50 | MRZ line 3 |
| idNumberValid | boolean | True if ID number check digit is valid, otherwise false | |
| dobValid | boolean | True if date of birth check digit is valid, otherwise false | |
| expiryDateValid | boolean | True if date of expiry check digit is valid or not available, otherwise false | |
| personalNumberValid | boolean | True if personal number check digit is valid or not available, otherwise false | |
| compositeValid | boolean | True if composite check digit is valid, otherwise false |
Class Error codes
| Code | Message | Description |
|---|---|---|
| 100 110 130 140 150 160 |
We have encountered a network communication problem | Retry possible, user decided to cancel |
| 200 210 220 |
Authentication failed | API credentials invalid, retry impossible |
| 230 | No Internet connection available | Retry possible, user decided to cancel |
| 240 | Scanning not available this time, please contact the app vendor | Resources cannot be loaded, retry impossible |
| 250 | Cancelled by end-user | No error occurred |
| 260 | The camera is currently not available | Camera cannot be initialized, retry impossible |
| 280 | Certificate not valid anymore. Please update your application | End-to-end encryption key not valid anymore, retry impossible |
| 290 | Transaction already finished | User did not complete SDK journey within token lifetime |
Netverify can be also implemented as a custom scan view. This means that only the scan view (including the scan overlays) are provided by the SDK. The handling of the lifecycle, document selection, readability confirmation, intermediate callbacks and all other steps necessary to complete a scan have to be handled by the application that implements the SDK as custom scan view!
To use the custom scan view with a plain scanning user interface, specify an instance of your class which implements the NetverifyCustomSDKInterface. You will receive a NetverifyCustomSDKController object.
NetverifyCustomSDKController netverifyCustomSDKController = sdk.start(yourNetverifyCustomSDKInterface);
Upon onNetverifyCountriesReceived within yourNetverifyCustomSDKInterface, specify country, document type and document variant to receive all relevant scan parts for the specific document.
@Override
public void onNetverifyCountriesReceived(HashMap<String, NetverifyCountry>
countryList, String userCountryCode) {
// YOURCODE
// List<ScanSide> netverifyScanSides = netverifyCustomSDKController.setDocumentConfiguration(netverifyCountries.get("USA"), NVDocumentType.PASSPORT, NVDocumentVariant.PLASTIC);
}
NetverifyCountry methods:
public String getIsoCode();
public Set<NVDocumentType> getDocumentTypes();
public Set<NVDocumentVariant> getDocumentVariants(NVDocumentType documentType);
NVDocumentType values: PASSPORT, ID_CARD, DRIVER_LICENSE
NVDocumentVariant values: PAPER, PLASTIC
NetverifyScanMode values: MRZ, BARCODE, FACE, MANUAL, OCR_CARD, OCR_TEMPLATE
NVScanSide values: FRONT, BACK, FACE
After onNetverifyResourcesLoaded within yourNetverifyCustomSDKInterface, start scanning by providing a ScanSide from the list, instances of the class NetverifyCustomScanView and NetverifyCustomConfirmationView, and an instance of your class which implements the NetverifyCustomScanInterface. You will receive a NetverifyCustomScanViewController object.
Add yourNetverifyCustomScanView to your layout and specify desired layout attributes using either
- a certain width, and height as wrap_content
- or a certain height, and width as wrap_content
- or width and height as match_parent (full screen).
Using width or height as wrap_content, the NetverifyCustomScanView attribute ratio needsto be set to any float value between screen width/screen height (e.g. portrait 720/1280 = ~0.6) and 4:3 (1.33). If your NetverifyCustomScanView is added to your layout via xml, specify the below namespace to access the custom attribute yourNameSpace:ratio. Face scans should only be done in portrait orientation with a recommended ratio of 0.7 or smaller.
xmlns:yourNameSpace="http://schemas.android.com/apk/lib/com.jumio.mobile.sdk"
Upon onNetverifyCameraAvailable within yourNetverifyCustomScanInterface, you can perform the following actions using the netverifyCustomScanViewController:
- Get the active scan mode
- Get the help text for the active scan mode
- Check if front and back camera available
- Check if front camera used
- Switch between front and back camera
- Check if flash available
- Check if flash enabled
- Switch flash mode (on or off)
- Check if scan fallback is possible
- Switch from default scan mode (MRZ or bar code) to fallback - remember to get the new scan mode and help text with the available getters after that
- Stop/Retry card scanning
- Pause/Resume extraction - the camera preview keeps running in the meantime
Call showShutterButton to determine if the image will be taken manually. If so, display your shutter button and call takePicture() once clicked.
To handle the activity lifecycle correctly, call pause and resume from the NetverifyCustomSDKController and NetverifyCstomScanPresenter if currently active.
Implement the following methods within
- NetverifyCustomScanInterface for camera, extraction, confirmation view and special notifications.
- NetverifyCustomSDKInterface for general SDK notifications.
Upon onNetverifyPresentConfirmationView, you can hide the scan view and show the confirmation view (asking user to confirm the image), retry and/or confirm the scan.
Note: yourNetverifyCustomScanView can be added to your layout by specifying any desired layout attributes.
Upon onNetverifyNoUSAddressFound after a Fastfill US driver license back side scan in barcode mode, you can start a front side scan in OCR mode (fallback) to receive the address if needed and/or confirm the scan.
Upon onNetverifyFaceOnBackside after a backside scan of an ID or Driver License, the scanning will restart automatically to let the user recapture his backside, as it seems that he has scanned the frontside accidentally instead of the backside because a face was detected.
Upon onNetverifyFaceInLandscape notify the user that he should rotate the device in portrait orientation to continue with face scanning.
Upon onNetverifyShowLegalAdvice it is necessary to display the provided legal advice to the user.
Upon onNetverifyScanForPartFinished, call netverifyCustomScanViewController.destroy() to release all resources before scanning the next part until all parts are scanned. Once completed, call netverifyCustomSDKController.finish() to finish the scan.
Instead of using the standard method onActivityResult, implement the following methods within yourNetverifyCustomSDKInterface for successful scans and error notifications:
The method onNetverifyFinished(NetverifyDocumentData documentData, String scanReference) has to be implemented to handle data after successful scans
Upon onNetverifyError(int errorCode, int detailedErrorCode, String errorMessage, boolean retryPossible, String scanReference), you can show the error message and/or call netverifyCustomSDKController.retry() if retryPossible.
Note: The error codes 200, 210, 220, 240, 260, 300, 310 and 320 will be returned.
After handling the result, it is very important to clean up the SDK by calling netverifyCustomSDKController.destroy() and netverifySDK.destroy().
To get information about callbacks, Netverify Retrieval API, Netverify Delete API and Global Netverify settings and more, please read our page with server related information.
© Jumio Corp. 268 Lambert Avenue, Palo Alto, CA 94306