ID Verification:Android integration

Limits

The SDK supports mobile devices, such as phones and tablets, that run Android 4.3 or later. The x86 architecture is not supported.

Permission description

For enhanced security, the SDK requires the following permissions:

SDK download and configuration

1. Download the Android SDK. The SDK is a standard Android Archive (AAR) package.

2. After the download is complete, decompress the package. Copy all AAR files from the Android SDK folder to the `libs` directory in 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-identityface-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/Android-AliyunFaceGuard-xxx.aar')
       implementation files('libs/idv-identitybase-sdk-xxx.aar') 
       implementation files('libs/idv-identityservice-sdk-xxx.aar') 
       implementation files('libs/idv-identityquality-sdk-xxx.aar') 
       implementation files('libs/idv-identityblink-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 add dependencies on the AAR files in the specified IDV ID Verification service SDK directory.
       //implementation(fileTree(dir: "libs", includes: ["*.aar"]))
   
       implementation "androidx.appcompat:appcompat:1.5.0"
       implementation "androidx.activity:activity:1.7.0"
       implementation "androidx.recyclerview:recyclerview:1.0.0"
       implementation 'com.squareup.okhttp3:okhttp:4.9.3'
       implementation 'com.squareup.okio:okio:2.8.0'
       implementation 'com.aliyun.dpa:oss-android-sdk:2.9.21'
       implementation 'com.alibaba:fastjson:1.1.72.android'
   }

   Note

   • In the preceding code, `xxx` represents the SDK version number.

   • The SDK requires all third-party dependency libraries to function correctly.

API reference

The Android SDK includes the `install`, `getMetaInfo`, and `verify` APIs.

Initialize the SDK (install)

• Function prototype

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

• Parameters

  • context: The context of the current application.

  • options: Specifies optional parameters for information collection. This parameter is optional. The optional parameters are as follows:

    Note

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

      Note: You can specify only one reporting site within a single application session lifecycle. The server query region must match the reporting site.

    • Specify a reporting site:

      • Singapore site (default): https://cloudauth-device.ap-southeast-1.aliyuncs.com

      • Indonesia site: https://cloudauth-device.ap-southeast-5.aliyuncs.com

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

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

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

    • For more information about the regions supported by product servers, see Supported regions.

    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 We recommend using the default configurations.	"1"
    CustomUrl	Sets the data reporting server domain name.	"https://cloudauth-device.ap-southeast-1.aliyuncs.com"
    CustomHost	Sets the data reporting server host.	"cloudauth-device.ap-southeast-1.aliyuncs.com

• Return value: None.

Get MetaInfo (getMetaInfo)

• Function prototype

  public static String getMetaInfo(Context context);

• Parameters

  Name	Type	Description
  context	Context	The context of the current application.

• Return value: Returns a string that contains the environment context of the mobile device in JSON format:

  {
    "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);

• Parameters

  Name	Type	Description
  transactionId	String	The `transactionId` obtained from the server-side Initialize API. Important Each `transactionId` can be used to call the `verify` function only once. Get a new `transactionId` before each call.
  extParams	Map<String, String>	Extension parameters. You can usually pass `null`. The supported custom fields are listed in the extParams configuration table below.
  callback	IdentityCallback	The callback interface for the verification result. For the return codes in the callback, see the IdentityResponse.code table below. The callback is defined as follows: 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	The color of the button at the bottom of the OCR result page.	#FF0000
  IdentityParams.RoundProgressColor	The color of the circle during the face scan.	#FF0000
  IdentityParams.ShowAlbumIcon	In the certificate OCR step, specifies whether to show the album upload entry. 1 (default): Show 0: Do not show	1
  IdentityParams.ShowOcrResult	In the certificate OCR step, specifies whether to show the result page. 1 (default): Show 0: Do not show	1
  IdentityParams.EditOcrResult	In the certificate OCR step, specifies whether the result page is editable. 1 (default): Editable 0: Not editable	1
  IdentityParams.MaxErrorTimes	The maximum number of retries. The range is 3 to 10. The default is 10.	10
  IdentityParams.CardOcrTimeOutPeriod	The timeout period for the OCR step. The range is 20 to 60 seconds. The default is 20 seconds.	20
  IdentityParams.FaceVerifyTimeOutPeriod	The timeout period for the liveness collection and detection step. The range is 20 to 60 seconds. The default is 20 seconds.	20
  IdentityParams.OcrResultTimeOutPeriod	The duration for which the OCR result page is editable. You can customize this value. By default, there is no limit.	60
  IdentityParams.SdkLanguage	You can customize the SDK language settings. By default, the SDK uses the mobile device's system language. Note For a list of languages supported by the SDK, see Custom languages for Android and iOS SDKs.	zh-Hans
  IdentityParams.CloseButtonLayout	The layout of the Close button. left (default): Left side right: Right side	left
  IdentityParams.WaterMark	The watermark text after a successful OCR scan.	Test watermark text
  IdentityParams.Protocol	SDK Protocol. Note Get the `protocol` from the server-side Initialize API and pass it in the extension parameters. This can reduce internal API interactions in the SDK and improve the network experience.	None

• IdentityResponse.code table

  Error code	Billed	Result code description
  1000	Yes	The user completed the face scan process, and the recommended verification result is "pass". This result is for reference only. Call the server-side CheckResult API to get the final verification result and proceed.
  1001	Yes	The user completed the face scan process, and the recommended verification result is "fail". This result is for reference only. Call the server-side CheckResult API to get the final verification result, the detailed reason for failure, and proceed.
  1002	No	System error.
  1003	No	SDK initialization failed. Check if the client time is correct.
  1004	No	Camera permission error. Try the following steps to resolve the issue: Before verification, make sure the app has camera permission. If the permission is granted but the error persists, try clearing the app cache and retrying.
  1005	No	Network error.
  1006	No	User exited.
  1007	No	Invalid TransactionId.
  1009	No	Client timestamp error.
  1011	No	Incorrect certificate type submitted.
  1012	No	Key information from the scanned certificate is missing or failed format validation.
  1013	No	Poor image quality.
  1014	No	The number of errors exceeded the upper limit.
  1015	No	The Android system version is too low.
  1016	No	Camera permission not granted.

Code example

public class MainActivity extends AppCompatActivity {
    private String transactionId = "";
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    
        // Initialize the 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 the transactionId.
         * The latest version also returns protocol data.
         */
        // transactionId = getTransactionIdFromServer(metaInfo).transactionId;
        // protocol = getTransactionIdFromServer(metaInfo).protocol;
        
        Map<String, String> extParams = new HashMap();
        // Set the protocol data
        extParams.put(IdentityParams.PROTOCOL, protocol);
        // Set the 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 configurations

-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.blink.BlinkRouter {*;}
-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

# Log obfuscation, optional
-assumenosideeffects class android.util.Log {
    public static *** d(...);
}

Demo code package

You can download the Android Demo to try it out.

Component trimming