ID Verification:Android integration

Limitations

Supported on Android 4.3 and later for phones and tablets.

x86 devices are not supported.

Required permissions

The SDK requires the following permissions at runtime.

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
tools:remove="true" />

Download and configure the SDK

1. Download the AAR package from the Client SDK release notes. You can also download the Android Demo to try out the features.

2. Extract the AAR files into your project's libs directory and add these dependencies to build.gradle.

   dependencies {
       // SDK modules 
       implementation files('libs/idv-identityplatform-xxx.aar') 
       implementation files('libs/idv-identityface-xxx.aar') 
       implementation files('libs/idv-identitycrypto-xxx.aar') 
       implementation files('libs/idv-identityocr-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-identitymouth-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') 
   
       // Or, use fileTree to specify the directory for the ID Verification SDK AAR files.
       //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.2.83_noneautotype'
   }

   Note

   • xxx is the SDK version number.

   • Include all third-party dependencies, or the SDK may not function correctly.

   • tygerservice-xxx.aar was removed in version 1.3.4.

   • idv-identitymouth-sdk-xxx.aar was added in version 1.3.6.

API reference

The SDK provides three APIs: install, getMetaInfo, and verify. Each is described below.

Initialize the SDK (install)

• Function prototype

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

• Parameters

  • context: Application context.

  • The options parameter, which is null by default, specifies optional data collection settings.

    Important

    • The ID Verification client includes a built-in security module known as the device helper. The device helper provides various data reporting regions to meet local data collection compliance requirements. You can set CustomUrl and CustomHost to specify different reporting sites based on user attributes.

    • Only one data reporting region can be specified per application session lifecycle. The region for server-side queries must match the reporting region. The supported regions vary by product. For more information, see Supported regions.

    • For each region, the CustomUrl 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

      • Malaysia (Kuala Lumpur): https://cloudauth-device.ap-southeast-3.aliyuncs.com

    Parameter	Description	Example
    IPv6	Indicates whether to use an IPv6 domain name to report device information: 0 (default): No (uses an IPv4 domain name) 1: Yes (uses an IPv6 domain name)	"1"
    DataSwitch	Controls when to report device information: 0 (default): When the SDK initializes 1: When you obtain a token Note The default setting is recommended.	"1"
    CustomUrl	Sets the server domain name for data reporting.	See CustomUrl for each region.
    CustomHost	Sets the server host for data reporting.	"cloudauth-device.ap-southeast-1.aliyuncs.com" Note This example is for the Singapore region. For server hosts in other regions, see CustomUrl for each region.

• Return value: None.

Get MetaInfo (getMetaInfo)

• Function prototype

  public static String getMetaInfo(Context context);

• Parameters

  Name	Type	Description
  context	Context	Application context.

• Return value: a JSON string with device environment information:

  {
    "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 transaction ID is single-use. Obtain a new one before each verify call.
  extParams	Map<String, String>	Extended parameters. Pass null if not needed. Supported fields: extParams configuration description.
  callback	IdentityCallback	Verification result callback. Return codes: IdentityResponse.code table. Callback definition: 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 Description

  Key	Description	Example (String type)
  IdentityParams.OcrResultButtonColor	Button color on the OCR result page.	#FF0000
  IdentityParams.RoundProgressColor	Circle color during face scanning.	#FF0000
  IdentityParams.ShowBlbumIcon	Show album upload entry during OCR: 1 (default): Show 0: Do not show	1
  IdentityParams.ShowOcrResult	Show OCR recognition result page: 1 (default): Show 0: Do not show	1
  IdentityParams.EditOcrResult	OCR result page editable: 1 (default): Editable 0: Not editable	1
  IdentityParams.MaxErrorTimes	Maximum retries. Range: 3–10. Default: 10.	10
  IdentityParams.CardOcrTimeOutPeriod	OCR recognition timeout. Range: 20–60 seconds. Default: 20 seconds.	20
  IdentityParams.FaceVerifyTimeOutPeriod	Liveness detection timeout. Range: 20–60 seconds. Default: 20 seconds.	20
  IdentityParams.OcrResultTimeOutPeriod	OCR result page edit timeout, in seconds. Default: unlimited.	60
  IdentityParams.SdkLanguage	You can customize the display language for the SDK. By default, the SDK uses your mobile device's system language. Note For a list of supported languages, see Customize languages for the Android and iOS SDKs.	zh-Hans
  IdentityParams.CloseButtonLayout	Layout of the Close button: left (default): Left side right: Right side	left
  IdentityParams.WaterMark	Watermark text displayed after successful OCR.	Test watermark text
  IdentityParams.Protocol	Protocol string from the server-side Initialize API response. Note Pass the protocol value from the server-side Initialize API response to reduce internal API calls and improve performance.	None

• IdentityResponse.code Table

  Status code	Billed	subCode	Description
  1000	Yes	A1000_1	Face scanning completed. Preliminary result: passed. Call the server-side CheckResult API for the authoritative result.
  1001	Yes	A1001_1	Face scanning completed. Preliminary result: failed. Call the server-side CheckResult API for the authoritative result and failure reason.
  1002	No	A1002_1	Failed to load model.
  		A1002_2	App moved to background; SDK exited on return to foreground.
  		A1002_3	Failed to load SO library.
  1003	No	A1003_1	Initialize API response is empty.
  		A1003_2	Initialize API response format is invalid.
  		A1003_3	Initialize API connection failed.
  		A1003_4	Initialize API response decryption failed.
  		A1003_5	Initialize API call failed (Code is not 200, or BizCode is not CODE_INIT_SUCCESS).
  		A1003_6	Initialize API OSS configuration is empty.
  		A1003_7	Context parameter is null.
  		A1003_8	Protocol parameter is null.
  1004	No	A1004_1	Front camera error.
  		A1004_2	Failed to open camera.
  		A1004_3	Rear camera error.
  1005	No	A1005_1	Network error during initialization.
  		A1005_2	Network error during verification.
  1006	No	A1006_1	User exited.
  1007	No	A1007_1	Invalid transactionId.
  A1008	No	A1008_1	NFC module missing.
  		A1008_2	OCR module missing.
  		A1008_3	Face module missing.
  1009	No		Client timestamp error.
  1010	No	A1010_1	install() was not called before verify().
  1011	No		Incorrect document type submitted.
  1012	No	A1012_1	Key document information missing or format validation failed.
  1013	No		Poor image quality.
  1014	No	A1014_1	Exceeded maximum error attempts.
  1015	No	A1015_1	Android version is too low.
  1016	No	A1016_1	Camera permission not granted.
  1017	No	A1017_1	Parameter exception: productCode is empty.
  2000	No	A2000_1	NFC configuration failed.
  		A2000_2	NFC permission not enabled.
  2002	No	A2002_1	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 the SDK
        IdentityPlatform.getInstance().install(MainActivity.this);
    
        // Get MetaInfo
        String metaInfo = IdentityPlatform.getMetaInfo(MainActivity.this);
    
        /**
         * Send MetaInfo to the app server. Call the cloud-side Initialize API to get the transactionId.
         * The new version returns 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 rules

-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.idv.identity.mouth.MouthRouter {*;}

-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(...);
}

# If using a version earlier than 1.3.2, add the following obfuscation rules:
-keepattributes Signature
-keepattributes *Annotation*
-keep class com.alibaba.fastjson.** { *; }
-keep class * extends com.alibaba.fastjson.TypeReference { *; }

Component trimming