ID Verification:Android integration

Limits

• Emulator mode debugging and x86 architecture are not supported.

• Only Android 4.4 or later is supported. The mobile device must support NFC.

Permission requirements

SDK download and configuration

1. Download the Android SDK. This SDK is a standard Android AAR package.

2. After downloading, extract the archive. Copy all AAR files from the Android SDK folder into the libs directory of your project. Then add the following dependencies to your project’s build.gradle file.

dependencies {
  // SDK modules 
  implementation files('libs/idv-identityplatform-xxx.aar') 
  implementation files('libs/idv-ientitycrypto-xxx.aar') 
  implementation files('libs/idv-identityocr-xxx.aar') 
  implementation files('libs/tygerservice-xxx.aar') 
  implementation files('libs/idv-identitybase-sdk-xxx.aar') 
  implementation files('libs/idv-identitymnn-xxx.aar') 
  implementation files('libs/idv-identityocrservice-xxx.aar') 
  implementation files('libs/idv-identitynfc-xxx.aar') 
  implementation files('libs/IDOCR_PubSDK_Android-1.0.0.aar') 

  // Alternatively, use fileTree to include all AAR files in the libs directory:
  //implementation(fileTree(dir: "libs", includes: ["*.aar"]))

  implementation "androidx.appcompat:appcompat:1.5.0"//upgrade
  implementation "androidx.activity:activity:1.7.0"
  implementation "androidx.recyclerview:recyclerview:1.0.0"//upgrade
  implementation 'com.squareup.okhttp3:okhttp:4.9.3'//upgrade
  implementation 'com.squareup.okio:okio:2.8.0'//upgrade
  implementation 'com.aliyun.dpa:oss-android-sdk:2.9.21'
  implementation 'com.alibaba:fastjson:1.1.72.android'
}

API reference

The Android SDK includes three APIs: initialize the SDK (install), retrieve MetaInfo (getMetaInfo), and start verification (verify).

Initialize SDK (install)

• Function prototype

public void install(Context context);
public void install(Context context,Map<String, String> options);

• Parameter description

  • context: The application context.

  • options: Specifies optional parameters for information collection. This parameter is optional and can be set to null. The parameters are as follows:

    Important

    • The ID Verification client includes a built-in Device Guard security module. To meet data collection compliance requirements in different regions, Device Guard provides different data reporting sites. You can set the CustomUrl and CustomHost parameters to specify a reporting site based on user properties.

    • Within the lifecycle of a single application session, you can specify only one data reporting region. The server-side query region must be the same as the reporting region. The supported regions vary by product. For more information, see Supported regions.

    • The CustomUrl for each region is as follows:

      • China (Hong Kong): https://cloudauth-device.cn-hongkong.aliyuncs.com

      • Singapore: https://cloudauth-device.ap-southeast-1.aliyuncs.com

      • Indonesia (Jakarta): https://cloudauth-device.ap-southeast-5.aliyuncs.com

      • US (Silicon Valley): https://cloudauth-device.us-west-1.aliyuncs.com

      • Germany (Frankfurt): https://cloudauth-device.eu-central-1.aliyuncs.com

    Field name	Description	Example
    IPv6	Specifies whether to use an IPv6 domain name to report device information: 0 (default): No (use an IPv4 domain name) 1: Yes (use an IPv6 domain name)	"1"
    DataSwitch	The timing for reporting device information. 0 (default): At initialization 1: When getting the token Note Use the default configurations.	"1"
    CustomUrl	Set the domain name of the data reporting server.	"https://cloudauth-device.ap-southeast-1.aliyuncs.com"
    CustomHost	Set the host of the data reporting server.	"cloudauth-device.ap-southeast-1.aliyuncs.com

• Return value: None.

Get MetaInfo (getMetaInfo)

• Function prototype

  public static String getMetaInfo(Context context);

• Parameter description

  Name	Type	Description
  context	Context	The application context.

• Return value: A JSON-formatted string containing environment context from the mobile device.

  {
    "apdidToken": "",
    "appName": "com.aliyun.identity.platform",
    "appVersion": "1.0.1",
    "bioMetaInfo": "5.1.0:11501568,4",
    "deviceBrand": "xxx",
    "deviceManufacturer": "xxx",
    "deviceModel": "xxx",
    "deviceType": "android",
    "identityVer": "1.0.0",
    "osVersion": "10",
    "sdkVersion": "1.0.9"
  }

Start verification (verify)

• Function prototype

  public void verify(String transactionId, Map<String, String> extParams, IdentityCallback callback);

• Parameter description

  Name	Type	Description
  transactionId	String	The transactionId obtained from the server-side Initialize API. Important Each transactionId can be used only once. Always obtain a new transactionId before each call to verify.
  extParams	Map<String, String>	Extended parameters. Pass null in most cases. Supported custom fields are listed in the table below. For details, see extParams configuration.
  callback	IdentityCallback	Callback interface for verification results. For return codes, see IdentityResponse.code table. Callback format: public class IdentityResponse { // See the description of "Return Code". public int code; // Result code description. public String message; } public interface IdentityCallback { boolean response(IdentityResponse response); }

• extParams configuration

  Key	Description	Example (String)
  IdentityParams.OcrResultButtonColor	Color of the bottom button on the OCR result page.	#FF0000
  IdentityParams.ShowBlbumIcon	Show album upload option during document OCR: 1 (default): Show 0: Hide	1
  IdentityParams.MaxErrorTimes	Maximum retry attempts. Range: 3–10. Default: 10.	10
  IdentityParams.CardOcrTimeOutPeriod	OCR timeout duration. Range: 20–60 seconds. Default: 20 seconds.	20
  IdentityParams.FaceVerifyTimeOutPeriod	Liveness detection timeout duration. Range: 20–60 seconds. Default: 20 seconds.	20
  IdentityParams.OcrResultTimeOutPeriod	Editable duration on the OCR result page. Customizable. Default: unlimited.	60
  IdentityParams.SdkLanguage	This section describes the custom language settings for the SDK. By default, the SDK uses the language of the mobile device's operating system. Note For a list of languages supported by the SDK, see Custom languages for Android and iOS SDKs.	zh-Hans
  IdentityParams.CloseButtonLayout	Close button layout: left (default): Left Right: Right side	left
  IdentityParams.WaterMark	Watermark text after successful OCR.	Test watermark text
  IdentityParams.Protocol	SDK protocol. Note Obtain the protocol from the server-side Initialize API and pass it in extParams to reduce internal SDK API calls and improve network performance.	None

• IdentityResponse.code table

  Error code	Billing	subCode	Result code description
  1000	Yes	A1000_1	The user completed the face scan process. The recommended verification result is 'Pass'. This result is for reference only. You can call the server-side CheckResult API to get the final verification result and proceed with the next steps.
  1001	Yes	A1001_1	The user completed the face scan process. The recommended verification result is 'Fail'. This result is for reference only. You can call the server-side CheckResult API to get the final verification result, the detailed reason for the failure, and proceed with the next steps.
  1002	No	A1002_1	Failed to load the model.
  		A1002_2	The app was moved to the background (Home button pressed). When the app returned to the foreground, the SDK actively exited.
  		A1002_3	Failed to load the .so library.
  1003	No	A1003_1	The content of the initialization API is empty.
  		A1003_2	The content format of the initialization API is incorrect.
  		A1003_3	Failed to connect to the initialization API protocol.
  		A1003_4	Failed to decrypt the content of the initialization API.
  		A1003_5	The initialization API call failed (Code is not 200, or BizCode is not 'CODE_INIT_SUCCESS').
  		A1003_6	The OSS information from the initialization API is empty.
  		A1003_7	An empty context was passed in.
  1004	No	A1004_1	An error occurred with the front-facing camera.
  		A1004_2	An error occurred when opening the camera.
  		A1004_3	An error occurred with the rear-facing camera.
  1005	No	A1005_1	A network error occurred with the initialization API.
  		A1005_2	A network error occurred with the verification API.
  1006	No	A1006_1	The user exited.
  1007	No	A1007_1	The TransactionId is invalid.
  A1008	No	A1008_1	The NFC module is missing.
  		A1008_2	The OCR module is missing.
  		A1008_3	The face module is missing.
  1009	No		The client timestamp is incorrect.
  1010	No	A1010_1	The `install` method was not called before the `verify` method.
  1011	No		The submitted ID document type is incorrect.
  1012	No	A1012_1	Key information from the recognized ID document is missing or failed format validation.
  1013	No		The image quality is poor.
  1014	No	A1014_1	The number of errors exceeded the upper limit.
  1015	No	A1015_1	The Android system version is too low.
  1016	No	A1016_1	Camera permission was not granted.
  1017	No	A1017_1	Parameter error: productCode is empty.
  2000	No	A2000_1	NFC configuration failed.
  		A2000_2	NFC permission is not enabled.
  2002	No	A2002_1	The device does not support NFC.

Sample code

public class MainActivity extends AppCompatActivity {
    private String transactionId = "";
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    
        // Initialize SDK
        IdentityPlatform.getInstance().install(MainActivity.this);
    
        // Get MetaInfo
        String metaInfo = IdentityPlatform.getMetaInfo(MainActivity.this);
    
        /**
         * Send MetaInfo to your app server, call the cloud Initialize API to get transactionId.
         * New versions also return protocol data.
         */
        // transactionId = getTransactionIdFromServer(metaInfo).transactionId;
        //protocol ==getTransactionIdFromServer(metaInfo).protocol;;
        
        Map<String, String> extParams = new HashMap();
        // Set protocol data
        extParams.put(IdentityParams.PROTOCOL, protocol);
        // Set SDK language
        extParams.put(IdentityParams.SdkLanguage, "en");
        // Start verification
        IdentityPlatform.getInstance().verify(transactionId, extParams,
                new IdentityCallback() {
                    @Override
                    public boolean response(final IdentityResponse response) {
                        if (IdentityResponseCode.IDENTITY_SUCCESS == response.code) {
                            Toast.makeText(MainActivity.this,
                                    "Verification passed", Toast.LENGTH_LONG).show();
                        } else {
                            Toast.makeText(MainActivity.this,
                                    "Verification failed([" + response.code + "]" +
                                            response.message + ")",
                                    Toast.LENGTH_LONG).show();
                        }
                        return true;
                    }
                });
    }
    
}

Obfuscation configuration

-verbose
-keep class com.idv.identity.platform.api.** {*;}
-keep class com.idv.identity.platform.log.** {*;}
-keep class com.idv.identity.util.IdentityUtils {*;}
-keep class com.idv.identity.ocr.IdentityOcrApi {*;}
-keep class com.idv.identity.platform.model.** {*;}
-keep class com.idv.identity.platform.config.** {*;}
-keep class com.idv.identity.face.IdentityFaceApi {*;}


-keep class com.face.verify.intl.** {*;}
-keep class com.alibaba.fastjson.** {*;}
-keep class face.security.device.api.** {*;}
-keep class net.security.device.api.** {*;}
-keep class com.dtf.toyger.** { *; }
-dontwarn net.security.device.api.**
-dontwarn face.security.device.api.**


-keep class com.idv.identity.service.algorithm.** {*;}
-keep class com.idv.identity.base.algorithm.** {*;}
-keep class com.idv.identity.quality.QualityRouter {*;}
-keep class com.idv.identity.service.IdentityFaceService {*;}
-keep class com.idv.identity.service.ocr.IdentityDocService {*;}

-keep class com.alibaba.sdk.android.oss.** { *; }
-dontwarn okio.**
-dontwarn org.apache.commons.codec.binary.**



# NFC
-keep class com.idv.identity.nfc.IdentityNfcApi { *; }
-keep class org.jmrtd.** {*;}
-keep class net.sf.**{*;}
-keep class org.**{*;}
-keep class cn.**{*;}


# Please add these rules to your existing keep rules to suppress warnings.
# This is generated automatically by the Android Gradle plugin.
-dontwarn com.fasterxml.**
-dontwarn com.google.**
-dontwarn java.applet.Applet
-dontwarn java.awt.**
-dontwarn javax.**
-dontwarn org.**
-dontwarn retrofit2.**
-dontwarn springfox.documentation.spring.web.json.Json

Demo code package

Download the Android Demo to try it out.