Overview

The greenID Native Mobile Toolkit is an iOS and Android framework that allows a high quality identity verification process to be embedded into mobile and tablet applications.

When invoked the toolkit captures basic identity information through an image that it takes of an ID card. It checks the ID card image for authenticity and presents that basic identity information to the consumer for review and amendment.

After review the toolkit captures a ‘selfie’ of the consumer. The selfie is compared to the photograph of the consumer extracted from the ID card.

Finally, the consumer’s identity is confirmed as valid by comparing the data extracted from the ID card against a database of valid identities.

This document describes aspects of the greenID Mobile Toolkit, how to install it, how to use it, and all configuration variables. This document contains some sample code to get you started as well.

Supported Platforms

The GreenID Mobile SDK is available for:

iOS 9 and above, with iPhone 5 and above;
Android Lollipop 5.0 (API 21) or above.

Size implications

For iOS and Android, you can expect your application's compiled size to grow by 30-40Mb

Requirements

In addition to the platform specific requirements below, the following must be in place before you can start using the greenID Mobile SDK:

You must have a greenID account. If you do not have one, or aren't sure, please contact your greenID representative to check.
You must have greenID credentials. The credentials comprise an "accountId" and "apiCode", which will be issued to you once your greenID account has been created and activated.

iOS Requirements

iOS 9 and above
iPhone 5 and above
GreenID SDK zip file with all supporting files
Xcode 8 or 9

Android Requirements

Android Studio V2.x or 3.x
A project that targets devices using Android Lollipop 5.0 (API 21) or above
GreenID SDK zip file with all supporting files

Platform Specific Integration Documentation

For platform specific integration instructions, please refer to sections below:

The Verification Process

A typical vanilla verification session follows this basic flow:

Your application decides that it is time for the consumer to verify their identity, and initialises the greenID Mobile SDK.
The SDK greets the consumer and gives them an overview of the verification process they will be going through.
Depending on your greenID configuration, the consumer may be prompted to choose the type of document they will use to help verify their identity.
The consumer is guided through the process of capturing an image of the front, and possibly the back, of their identity document.
The image is checked for quality and sent to greenID for authentication and automatic data extraction.
The consumer is guided through the process of taking a selfie for comparison to their identity document.
The selfie is sent to greenID for comparison against the image on the identity document.
The consumer is presented with the information that was extracted from their identity document (if any), and asked to check it, and correct it if necessary.
The SDK sends the data to GreenID, which registers a new verification attempt, runs any background checks that are configured, and returns the status to the SDK.
If the configured verification rule has not been satisfied, then an interactive session is launched, and the consumer can select from various options to complete the verification process.
Once the verification process is complete, the SDK does a "handoff" to your application with the ID of the verification attempt, and the overall status. Your application can then make a decision about the next step in the workflow. Your application can make a secure query to greenID to get the full outcome of the verification process; this is highly recommended.

There are only two contact points your application has with the SDK: initialisation and handoff. The SDK handles the rest of the on-boarding and identity verification process.

Returning User Mode

The process described in the previous section applies to the "on-boarding" mode of greenID Mobile. In on-boarding mode, a new verification attempt is registered with greenID every time a person begins the process. However, verification attempts may be registered with greenID via another channel, such as a web service call, and the person can pick up the process on a mobile device for the purpose of photographing an ID document. This is referred to as "returning user" mode.

Starting a verification session in returning user mode requires slightly different configuration parameters. These are documented in the section Configuration Variables.

Using "returning user" mode requires the use of a verification token. It is recommended that your native mobile application makes a call to your back end, which in turn makes a call to greenID to fetch a verification token. This is the most secure option. For details on how to fetch a verification token, please refer to the getVerificationToken web service.

Querying the Outcome of the Verification Process

After the verification process is complete, the outcome must be securely queried from greenID.

RESTful Web Service

The simplest way to query the outcome is to use the RESTful web service provided by greenID. The web service can be invoked by performing a HTTP GET against the base URL being used plus “/df/verificationResult” with the following query parameters:

accountId – the customer’s greenID account ID. Issued by greenID.
webServicePassword – the customer’s web service password, note that this is not the same as the apiCode.
verificationToken – identifies which verification session to fetch the result for. Note that the verificationToken must be current, and therefore this action must be performed within 30 minutes of the person completing the verification session.

An example request is: https://test-au.vixverify.com/df/verificationResult?accountId=xxxyyyy&webServicePassword=zzzz&verificationToken=914d98541cdc5e08ed0bdb3187b3edc93395b9de

The web service will return a JSON fragment with all the details of the person and the overall status of the verification attempt. See Old Verification Result Variables for a list of the variables and explanations for each of them.

WSDL Web Service

Whilst using our RESTful webservice is the easiest method to intergate for simple intergrations, it does not return as much detail about a the verification attempt. If your usage senario requires more detail you may need to intergrate using our greenID API web service. Information on how to intergrate using greenID API in general is avalible on the Version 3 greenID API page. For information on how to get the results for a verification attempt made through the GreenID Mobile SDK please take a look at the GetVerificationResult section of the Web Method Details V3 page.

Accessing Image and OCR information for greenID Mobile

For information on how to get the raw and confirmed OCR data back after the verificaiton process as well as document images please refer to the Old Accessing Image and OCR information page.

Styling the screens

The SDK is predominantly made up of HTML/CSS pages served via native web views. You can use the customCssPath parameter to pass in a URL that points to a CSS file residing on your server. This CSS file can include overrides to any of the default style rules so that the screens can adhere to your own branding requirements.

Note: you can't modify the styling for the document capture widget or the face capture widget.

Your CSS file should contain only overrides to the specific rules that you need. Don't take a copy of the default CSS and modify that, because if you do then you'll essentially be loading the same file twice, unnecessarily increasing loading time.

We've created a tool to help you figure out what selectors you need to use to override different elements. You can use the following page and your browser's dev tools to grab the necessary selectors, and to see your CSS file in action.

The SDK styling helper: http://mockup.edentiti.com/greenid-mobile/