Before you begin

If upgrading from an earlier version of greenID SDK, please check below for special upgrade steps before proceeding.  The 3.x version has major changes to gradle and aar dependencies. 

Prerequisites

This process assumes the following:

• You are running Android Studio 3.x (Latest tested was 3.6.3) (Android Studio 4.x may work)
• You are integrating v3.0.0 or higher of the greenID Mobile Android SDK (Latest is v3.0.2)
• You are using V5.6.0 or higher of the Gradle wrapper (Latest tested was 5.6.4), confirm this by checking your project's gradle-wrapper.properties file's distributionUrl property:
  

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

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

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

• You are targeting a minSdkVersion of no less than 24 (Confirm in application's build.gradle file)
• You are using compileSdkVersion 29 or higher (Latest tested was 29)
• You are using targetSdkVersion 29 or lower (Latest tested was 29)
• Targeting Java 8
• AndroidX is required
• Kotlin 1.3+

A note on AndroidX

The GreenID Mobile SDK now uses AndroidX support libraries.  If your application does not use AndroidX, then please use the "Migrate to AndroidX..." menu option in Android Studio to upgrade your project.  Make sure you use some sort of version control system (git, svn, etc) before you run the migration.  Alternatively, have a look at the "android.enableJetifier" option for gradle.

Experiencing odd layout issues or camera behaviour?

Under some very specific conditions, after integrating our SDK, you may find some document or selfie capture layout issues and/or camera behaviour.  As a first step to possibly fix this, you may try to delete your Gradle cache folder after closing Android Studio.  The Gradle cache folder is typically found at $HOME/.gradle/caches/  

Integrating greenID SDK

Build settings

• Unzip the GreenID Android SDK distribution zip file to a temporary location
• Copy the greenidsdk.aar file 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 below, if not, add the following lines to the bottom of the file.

• Also, add the following Maven repository, to access the 'IDscan' repository 

  
  

   repositories {
      maven {
         url "s3://maven-mobile-repo/releases"
         credentials(AwsCredentials) {
                  accessKey "AKIAT35UXA7VX6BTJAN4" 
                  secretKey "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"
         }
      }
      flatDir {
         dirs 'libs'
      }
  }
   

• Add the following lines into the "dependencies" section of your application's build.gradle file (Please note, order is important) (Also note, the version numbers below are the version numbers successfully tested):

  greenID SDK dependencies

      implementation 'org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.3.72'
      implementation 'androidx.appcompat:appcompat:1.2.0'
      implementation 'androidx.constraintlayout:constraintlayout:2.0.4' // Do *not* use 2.1.0-alpha2 - it breaks some layouts
      implementation 'androidx.coordinatorlayout:coordinatorlayout:1.1.0'
      implementation 'androidx.lifecycle:lifecycle-extensions:2.2.0'
      implementation 'androidx.recyclerview:recyclerview:1.1.0'
      implementation 'androidx.localbroadcastmanager:localbroadcastmanager:1.0.0'
      api 'org.jetbrains.kotlinx:kotlinx-coroutines-core:1.3.2'
      api 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.2'
  
      implementation group: 'commons-io', name: 'commons-io', version: '2.6'
  
      implementation project(':greenidsdk_resources') 
  
      implementation ('com.idscan.ieos:mjcs:10.5.1')
      implementation 'com.idscan.ides:default-AUS-profile:3422'
  
  // The following two lines should _NOT_ be included if your account is configured for *Passive Liveness*
  //    implementation 'com.idscan.idfb:liveness-core:0.6.1'
  //    implementation 'com.idscan.idfb:liveness:0.6.1'
     
      implementation(name: 'greenidsdk', ext: 'aar')
  
      implementation('com.google.code.gson:gson:2.8.5') 
      api 'org.greenrobot:eventbus:3.0.0'
  
      implementation 'me.grantland:autofittextview:0.2.1'
  
      implementation('com.google.android.gms:play-services-location:18.0.0')
  
      implementation ('com.github.hotchemi:permissionsdispatcher:3.3.2') { exclude group: 'com.android.support' }
      annotationProcessor 'com.github.hotchemi:permissionsdispatcher-processor:3.3.2'
      api 'com.loopj.android:android-async-http:1.4.9'
      implementation 'androidx.percentlayout:percentlayout:1.0.0' 
      implementation 'pl.droidsonroids.gif:android-gif-drawable:1.2.16' 
  
  
     

• If you have issues with duplicate statically linked 3rd party libraries, you can fix this by adding the following to the bottom of the android section your app's build.gradle file:

  packagingOptions {

  pickFirst 'lib/name/of/library.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"
          }
      }
  }
  
  

• Make sure you are targeting Java 1.8, by adding the following lines to the android section of your app's build.gradle file:
  

  android {
      compileOptions {
          sourceCompatibility JavaVersion.VERSION_1_8
          targetCompatibility JavaVersion.VERSION_1_8
      }
  }

• 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 org.apache.http.** { *; }
  
  -dontwarn org.apache.**
  -dontwarn com.vixverify.**
  -dontwarn com.scottyab.rootbeer.**
  
  -keepattributes *Annotation*
  -keepclassmembers class ** {
      @org.greenrobot.eventbus.Subscribe <methods>;
  }
  -keep enum org.greenrobot.eventbus.ThreadMode { *; }

gradle.properties settings

We now use AndroidX, and you will need to turn this on in your gradle.properties file.  

Suggested gradle.properties settings are:

android.useAndroidX=true
android.enableJetifier=true

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.  

There are important changes for the 3.x Android SDK, so make sure you revise the customisation page.  

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 a library that allows 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 3.x