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.

  • options: Optional parameters for data collection. Defaults to null. It accepts the following parameters:

    Important

    • The ID Verification client includes a built-in device helper security module. To comply with data collection requirements across different regions, the client supports multiple data reporting sites. You can use the CustomUrl and CustomHost parameters to specify a reporting site based on user attributes.

    • You can specify only one data reporting region per application session lifecycle. This region must match the one used for your server-side queries. Server-side region support varies by product. For details, see Supported regions.

    • Regional CustomUrl values:

      • 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	Specifies 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	Specifies when to report device information. 0 (default): At initialization 1: When getting a token Note We recommend using the default setting.	"1"
    CustomUrl	The domain name of the data reporting server.	For details, see Regional CustomUrl values.
    CustomHost	The host of the data reporting server.	"cloudauth-device.ap-southeast-1.aliyuncs.com" Note This example is for the Singapore region. Hosts for other regions can be derived from the URLs listed in Regional CustomUrl values.

• 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	This webhook delivers authentication results. For more information about the return codes in the callback, see Native SDK client result codes and sub-codes. 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 set a custom display language for the SDK. By default, it uses the mobile device's system language. Note For a list of supported languages, see Android and iOS SDK Language Customization.	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

Result codes

For more information, see Native SDK client result codes and sub-codes.

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

You can trim some components during the SDK integration phase. To minimize the SDK package size, integrate only the components that your product requires. This ensures a complete set of features and security compliance. For detailed trimming rules, see SDK thinning instructions.