Before you begin

If upgrading from an earlier version of greenID SDK, please check below for special upgrade steps before proceeding.  Pay special attention to the "Upgrading to 2.8.x" section, as there is a major change in how to receive results back from the SDK.

Prerequisites

This process assumes the following:

• You are running Android Studio 3.x (Latest tested was 3.5.3)
• You are integrating v2.8.1 or higher of the greenID Mobile Android SDK
• You are using V4.10.1 or higher of the Gradle wrapper (Latest tested was 5.1.1), confirm this by checking your project's gradle-wrapper.properties file's distributionUrl property:
  

  distributionUrl=https\://services.gradle.org/distributions/gradle-4.10.1-all.zip
  
  

• You are using V3.3.1 or higher of the Gradle tools (Latest tested was 3.4.2), confirm this by checking your project's build.gradle file:
  

  classpath 'com.android.tools.build:gradle:3.3.1'
  
  

• You are targeting a minSdkVersion of no less than 24 (Confirm in application's build.gradle file)
• You are using compileSdkVersion 27 or higher (Latest tested was 28)
• You are using targetSdkVersion 27 or lower (Latest tested was 28)

A note on AndroidX

The GreenID Mobile SDK does not currently use the AndroidX support libraries.  If the application that our SDK is to be integrated into does use AndroidX, then please use the "Migrate to AndroidX..." menu option in Android Studio once integration is complete, to allow it to update the appropriate dependencies to be AndroidX dependencies.

Integrating greenID SDK

Build settings

• Unzip the GreenID Android SDK distribution zip file to a temporary location
• Copy the included .aar files into your applications /libs folder (Typically /app/libs)
• Copy the included greenidsdk_resources folder to the top-level folder of your project

Project settings.gradle

• Add ":greenidsdk_resources" to the "include" line in your project's settings.gradle file, for a default project, the line will look like this:
  

  include ':app', ':greenidsdk_resources'

Application build.gradle

• Ensure your app's build.gradle file has a `flatDir` section in the repositories section similar to the below, if not, add the following lines to the bottom of the file:

  repositories {
      flatDir {
          dirs 'libs'
      }
  }

• Add the following lines into the "dependencies" section of your application's build.gradle file (Please note, order is important):

  greenID SDK dependencies

      annotationProcessor 'com.github.hotchemi:permissionsdispatcher-processor:3.3.2'
      // Adjust version number as per your compileSdkVersion
      implementation 'com.android.support:appcompat-v7:27.1.1'
      implementation 'com.android.support:design:27.1.1'
      implementation 'com.android.support:recyclerview-v7:27.1.1'
      implementation 'com.android.support.constraint:constraint-layout:1.1.3'
      implementation 'com.android.support:support-v4:27.1.1'
      implementation 'com.android.support:percent:27.1.1' 
      implementation 'com.google.code.gson:gson:2.8.0'
      implementation 'me.grantland:autofittextview:0.2.1'
      implementation 'com.google.android.gms:play-services-vision:11.0.0'
      implementation 'com.google.android.gms:play-services-location:11.0.0'
      implementation ('com.github.hotchemi:permissionsdispatcher:3.3.2') { exclude group: 'com.android.support', module: 'support-v13' }
      implementation 'pl.droidsonroids.gif:android-gif-drawable:1.2.7'
      implementation(name: 'greenidsdk', ext: 'aar')
      implementation project(':greenidsdk_resources')
      api 'org.greenrobot:eventbus:3.0.0'
      api 'com.loopj.android:android-async-http:1.4.9'
      implementation(name: 'catfishairdocscansdk', ext: 'aar')
      implementation(name: 'catfishairselfiesdk', ext: 'aar')
      implementation(name: 'ifacerec-VIX-Linux-6.4.0.538', ext: 'aar', { changing = true })

• Ensure no duplicate statically linked 3rd party libraries attempt to get copied into your application's apk when being built, by adding the following to the bottom of the android section your app's build.gradle file:

  packagingOptions {
      pickFirst 'lib/armeabi-v7a/libopencv_java3.so'
      pickFirst 'lib/armeabi/libopencv_java3.so'
      pickFirst 'lib/arm64-v8a/libopencv_java3.so'
  }

• Ensure no emulator architectures are included for the application by adding the following to the bottom of the android section of your app's build.gradle file:
  

  flavorDimensions "base"
  productFlavors {
      universal {
          dimension "base"
          ndk {
              abiFilters "armeabi-v7a", "arm64-v8a"
          }
      }
  }
  
  

• Add the following string to your application's strings.xml resource file, being sure to make the value of the string be something unique, like your application ID:

  <string name="content_authority">YOUR_APPLICATION_OR_OTHER_UNIQUE_ID_HERE</string>
  
  

• Allow multiple Dex files in your apk by adding the following into the defaultConfig section inside the android section of your app's `build.gradle` file:

  multiDexEnabled true

• Sync your project files with the gradle files when prompted.

Application proguard-rules.pro

• Ensure no compiler warnings during release builds by adding the following to your proguard rules file:
  

  -keep class com.vixverify.** { *; }
  -keep class com.idmetrics.** { *; }
  -keep class au.com.imagus.** { *; }
  -keep class at.nineyards.anyline.** { *; }
  -keep class org.apache.http.** { *; }
  
  -dontwarn at.nineyards.anyline.**
  -dontwarn com.microblink.**
  -dontwarn org.apache.**
  -dontwarn com.vixverify.**
  -dontwarn au.com.imagus.**
  -dontwarn au.com.imagus.ifacerec.**
  -dontwarn com.scottyab.rootbeer.**
  
  -libraryjars libs(!at.nineyards.anyline.**)
  
  -keepattributes *Annotation*
  -keepclassmembers class ** {
      @org.greenrobot.eventbus.Subscribe <methods>;
  }
  -keep enum org.greenrobot.eventbus.ThreadMode { *; }

Optional R8 and D8 tools

Two new tools were introduced in Android Studio recently, called D8 and R8.  Integration of the GreenID SDK using these two tools were tested, and with a small update to the proguard rules file, appear to have no adverse effects on the integration process.  As (at least) R8 is the default shrinker for Android Studio, you may use it by adding the following to your application's build.gradle file:

android.enableR8=true

As "fullMode" for R8 is still experimental, we suggest caution enabling it for your application, and we do not support it being enabled when integrating our SDK.

D8 is not enabled by default for new Android Studio projects, but if you would like to enable it, add the following to your application's build.gradle file:

android.enableD8=true

As "fullMode" for D8 is still experimental, we suggest caution enabling it for your application, and we do not support it being enabled when integrating our SDK.

In both cases, if experiencing strange behaviour during compilation, minifying or packaging of your app, please disable one or both of D8 and R8 and try again.

Manifest

Open your application's AndroidManifest.xml file and make the following changes:

• Add the following property to the top-level <manifest> tag:
  

  xmlns:tools="http://schemas.android.com/tools"
  
  

• Add the following property to the <application> tag:

  tools:replace="android:allowBackup,icon,theme"

Getting logging and analytics from the SDK

The SDK can pass log events, including some events that can be used for analytics in your app.  This is optional - if you don't want your app to receive log messages, then you don't need to implement this code. 

Note that if you implement these methods, the SDK will stop logging some messages to the standard Android logs, as it will be sending them to your handler function instead.  

To get logging messages:

• First set up a class that implements GIDLogClientHandler to handle the log messages.  This can be the same class that starts the GreenID SDK.
• Next, set the log level that the SDK will use.  To receive all events, including analytics, use GIDLog.LevelUI. If you don't set a level, the default is GIDLog.LevelInfo, which is a subset of the logging events.  
• Tell the SDK which class is acting as the log handler  using GIDLog.setLogClientHandler()
• Finally, implement the required method to receive the log messages: public void sdkDidLogLevel() Inside this method you can filter messages based on the log level, or analytics code, and print them or send them on to other analytics services.  

The sample code includes this setup code and an example delegate method.

Sample Code

Please see the sample code project for a working example of how to integrate our SDK.

Sample code can be found here.

Return values

As of Android SDK v2.7.8, we introduced a new way to start and get data back from our SDK.  Please see the sample code on how to instantiate the new GreenID class, and how to implement the new GreenIDListener listener interface to get responses back.  The BroadcastReceiver way of receiving the result back still functions, but is now deprecated.

The SDK will call either the onGreenIDSuccess or onGreenIDFailed listener methods.  The data that gets sent back to the listener will contain a RESULT_CODE value, and then either a verification token and result for a successful completion of the SDK, or a short and long result description pair of values for an error, as seen in the sample code above.

The various result code values that can be returned are:

Querying Details of the Verification Process

The verificationToken that is required to query the outcome of the verification process (see Querying) is passed to the GreenIDListener's onGreenIDSuccess method.

Verification result and intent result differences

The GreenIDListener.onGreenIDFailed() method call will only be called if the data capture and verification process did not complete all the way through, for reasons such as the user backing out of or cancelling the process, a lack of network connectivity, or some other error condition.  This method call will always be called with a ResultCode other than SUCCESS.

The GreenIDListener.onGreenIDSuccess() method call will only be called if the data capture and verification process completed all the way through, regardless of the result status of verification process. It is possible to receive a SUCCESS ResultCode back, even if the verification process did not complete successfully, for example, the user decides to select the “Save and continue later” option at the end of the process. In this case, the verificationStatus value should be read and used to determine how to proceed.

A non-success verificationStatus (such as IN_PROGRESS) is not considered an error condition.

Please see our greenID API documentation for more information about verification statuses and what they mean and how to retrieve more information about a verification.

Customising the workflow UI

There are a number of pieces of the UI that can be customised in the SDK.  This should be done in conjunction with CSS customisation to change the UI of the web views used in the workflow.  To give the best user experience, you should make your CSS and SDK customisations consistently.  

For a full guide to customising the Android SDK UI, please refer to the Android UI Customisation page.

Emulator-enabled testing SDK libraries

As of v2.7.4 of the greenID SDK distribution zip file, we are including two libraries that allow developers to still do the integration work to integrate the greenID Mobile SDK, but be able to test their own application within an emulator still.  Please see our Using the greenID simulator-enabled Android libraries wiki page on how to use these alternate library files.

Upgrading from previous versions

Upgrading to 2.8.x

This SDK version no longer sends a broadcast for responses from the SDK, but instead we've implemented a Listener pattern.

To upgrade to our SDK v2.8.x, please follow these steps:

• Implement the GreenIDListener interface to receive results back from the SDK.
  

  For example:
  Previously, you were required to register a BroadcastReceiver, and override its "OnReceive()" method like this:
  
  

  BroadcastReceiver onReceive()

  @Override
  public void onReceive(Context context, Intent intent) {
      log("onReceive() called with: context = [" + context + "], intent = [" + intent + "]");
  
      unregisterGreenIDBroadcastReceiver();
  
      try {
          String action = intent.getAction();
          if (action.equalsIgnoreCase(GREENID_RETURN_INTENT_ACTION)) {
  
          int resultCode = intent.getIntExtra("RESULT_CODE", -1);
          log("Back from greenID SDK");
  
          switch (resultCode) {
               case ResultCode.SUCCESS: {
  
  // etc. etc. etc.

  
  

  New GreenIDListener

  // As an example, within your activity:
  
  public class MainActivity implements GreenIDListener {
  
  @Override
  public void onGreenIDSuccess(int resultCode, String verificationToken, String verificationStatus) {
      // Success here - your business logic
  }
  
  @Override
  public void onGreenIDFailed(int resultCode, String message, String description) {
  	// Failure here - your business logic
  		switch (resultCode) {
  			case ResultCode.SUCCESS: {
  				// etc etc etc
  }

• Remove the logic for registering the old broadcast receiver
  
  

• To start the GreenID SDK, still construct your configuration bundle, but start it using the following code:

  Starting GreenID SDK

  try {
     GreenID.getInstance(getApplicationContext()).setListener(this);
     GreenID.getInstance(getApplicationContext()).start(configBundle);
  } catch (GreenIDConfigException e) {
     // You have to handle this!
  }

  NOTE: You must handle the configuration exception appropriately.

Please our sample code for an example of the new listener interface.

Upgrading to 2.7.10

This SDK version no longer requires the following dependency, so it can be removed from your application's build.gradle file, unless your application requires it:

implementation 'org.apache.httpcomponents:httpmime:4.2.1'

Upgrading from 2.4.34 to 2.5.x

If upgrading from v2.4.34 to v2.5.x, the following steps need to be followed:

• Remove the following files from your app's libs/ folder:
  

  api-release.aar
cardio-release.aar
misnapcamera-release.aar
misnapscience-release.aar
sanselan-release.aar
catfishair.aar
greenidsdk.aar

  
  

• Remove the following lines from your app's build.gradle file:
  

  compile(name: 'catfishairsdk', ext: 'aar')
compile(name: 'api-release', ext: 'aar')
compile(name: 'misnapcamera-release', ext: 'aar') { exclude module: 'appcompat-v7' }
compile(name: 'misnapscience-release', ext: 'aar') { exclude module: 'appcompat-v7' }
compile(name: 'sanselan-release', ext: 'aar')
compile(name: 'cardio-release', ext: 'aar')
compile 'de.greenrobot:eventbus:2.4.0'



• If you are including the following configuration parameters into the GREENID_CONFIG bundle when calling the greenID SDK, they may be removed as they are no longer used:
  
  selfieEyeThreshold
selfieNumberOfBlinks
catFishUrl
catFishMerchantKey
catFishSecretKey