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 8 and above, with iPhone 5 and above;
• Android KitKat 4.4.4 (API 19) or above.

Size implications

• For iOS, you can expect your application's compiled size to grow by about 25mb
• For Android, you can expect your application's compiled size to grow by about 15mb

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 8 and above
• iPhone 5 and above
• GreenID SDK zip file with all supporting files

Android Requirements

• Android Studio V2.0 or higher (latest is V2.2 at time of writing)
• A project that targets devices using Android KitKat 4.4 (API 19) or above
• GreenID SDK zip file with all supporting files

Platform Specific Integration Documentation

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

• Android integration
• iOS integration

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.

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://test2.edentiti.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 Verification Result Variables for a list of the variables and explanations for each of them.

Accessing Image and OCR information for greenID Mobile

Overview

To access image and OCR information from greenID mobile, including but not limited to; raw OCR information, confirmed user information and document images the DocumentImageServiceV2 is used. This webservice provides this information for each combination source attempt for a given verificationId. 

Setup

This is a WSDL based web service and as such is consumed in the normal WSDL way using the below URLs. 

This webservice can be accessed on our test server using: https://test-au.vixverify.com/Registrations-Registrations/DocumentImageServiceV2?wsdl

And in production using: https://au.vixverify.com/Registrations-Registrations/DocumentImageServiceV2?wsdl

Request Parameters

Required Parameters:

accountId - The account code provided to you as a customer for use with greenID

password - The webservice password provided to you as a customer for use with greenID

verificationId - The verificationId of the verification you wish to get the information for.

Optional Parameters:

getConfirmedOcrData - Set to true to get the confirmed ocr data for all combination source attempts.

getRawOcrData - Set to true to get the raw ocr data for all combination source attempts.

getImageData - Set to true to return document image and selfie information for all combination source attempts. Please note that this function is disabled by default, please contact us at support@edentiti.com to have this enabled for your account.

Optional parameters are passed into the webservice using the a param tag which needs the parameter name and value to be set. All of the parameters can be set to either true or false and will include or exclude their corresponding elements based on the setting, true will return the corresponding data, false will exclude it. If a parameter is not provided it will default to false.

The operation which returns the image data is more intensive for us then the other two so we ask that you keep your calls to get the image data to a minimum.

Example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dyn="http://dynamicform.services.registrations.edentiti.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <dyn:getInfoForAllDocuments>
         <accountId>account_id</accountId>
         <password>web-service-password</password>
         <verificationId>A1a1aAAA</verificationId>
         <param>
            <name>getConfirmedOcrData</name>
            <value>true</value>
         </param>
         <param>
            <name>getRawOcrData</name>
            <value>true</value>
         </param>
         <param>
            <name>getImageData</name>
            <value>true</value>
         </param>
      </dyn:getInfoForAllDocuments>
   </soapenv:Body>
</soapenv:Envelope>

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
   <env:Header/>
   <env:Body>
      <ns2:getInfoForAllDocumentsResponse xmlns:ns2="http://dynamicform.services.registrations.edentiti.com/">
         <return>
            <document>
               <confirmed>
                  <confirmedItem>
                     <name>surname</name>
                     <value>SMITH</value>
                  </confirmedItem>
                  <confirmedItem>
                     <name>documentNumber</name>
                     <value>A1111111</value>
                  </confirmedItem>
               </confirmed>
               <images>
                  <imageItem>
                     <index>FRONT</index>
                     <url>https://s3-ap-southeast-2.amazonaws.com/public.folder.test/images/123.jpg</url>
                  </imageItem>
                  <imageItem>
                     <index>FACE</index>
                     <url>https://s3-ap-southeast-2.amazonaws.com/public.folder.test/images/1234.jpg</url>
                  </imageItem>
                  <imageItem>
                     <index>SELFIE</index>
                     <url>https://s3-ap-southeast-2.amazonaws.com/public.folder.test/images/12345.jpg</url>
                  </imageItem>
               </images>
               <raw>
                  <rawItem>
                     <name>surname</name>
                     <value>SMITH</value>
                  </rawItem>
                  <rawItem>
                     <name>documentNumber</name>
                     <value>A2222222</value>
                  </rawItem>
               </raw>
               <region>NZ</region>
               <subregion>unknown</subregion>
               <type>PASSPORT</type>
            </document>
         </return>
      </ns2:getInfoForAllDocumentsResponse>
   </env:Body>
</env:Envelope>

Return Data

It is important to note that though this example only contains one document object real results may contain none or several as a single verification can have multiple combination source attempts. The same is true for confirmedItems and rawItems, real results are likely to contain many more results, but will provide these additional fields in the same format.

• document - This is a single document container, it represents a single combination source attempt and contains all other return data.
  • region - The region of the document used for the combination source attempt.
  • subregion - The subregion of the document used for the combination source attempt, will default to "unknown" if no subregion is used on the document.
  • type - The document type of the combination source
  • confirmed - An object which contains the list of confirmedItems.
    • confirmedItem - A single confirmed data item such as a name or document number. 
      
      • name - The name of the field, could also be considered to be key.
      • value - The value of the field
  • images - an object which contains the list of images for the combination source
    • imageItem - A single imageItem object containing information about a single image.
      • index - the index contains the type of image, possibilities include: FRONT, BACK, FACE and SELFIE. Please note that not all documents will have any or all of these indexes attached since they are not always captured depending on the account settings and the how the capture process went for the user.
      • url - The url of the image file
  • raw - an object which contains the list of rawItems, can be empty if no fields were successfully OCRed off the document.
    • rawItem - A single raw data item such as a name or dob, etc. Please note that these field can contain all sorts of weird and wonderful characters since it is the raw output from the OCR process. In addition only the fields which were successfully OCRed will be returned, the fields returned can and will fluctuate depending on the OCR result.
      • name - The name of the field,could also be considered to be key.
      • value - The value of the field

Possible Names

Regarding the rawItem and confirmedItem names the current list of possible keys are:

General

• givenname
• middlename
• surname
• dob
• country

Document Related

• documentNumber
• secondaryDocumentNumber
• documentExpiryDate
• documentIssueDate
• documentType
• documentRegion
• documentGender

Address Related

• propertyName
• flatNumber
• streetNumber
• streetName
• streetType
• postcode
• townCity
• state

Last Updated: 02 Dec 2016 

Notes on the name list

• This list is likely to expand as more document types with weird and wonderful fields continue to be added.
• The rawItem list will almost always only contain a subset of the confirmedItems since extra data (such as documentRegion and country) are added when the confirmed data is passed. 

Common Problems and Solutions

<env:Envelope>
   <env:Header/>
   <env:Body>
      <ns2:getInfoForAllDocumentsResponse>
         <return/>
      </ns2:getInfoForAllDocumentsResponse>
   </env:Body>
</env:Envelope>

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/