ID Verification provides a client SDK for Android to help you implement electronic Know Your Customer (eKYC) features in your business application. You can call the Initialize operation to obtain a unique transactionId and use the transactionId to start the client SDK. This topic describes how to integrate ID Verification client SDK for Android with an application and provides the sample code.
Limits
The SDK supports only mobile phones or tablets that run Android 4.3 or later. The x86 architecture is not supported.
Permissions
The SDK requires the permissions described in the following table. To improve security, users can determine whether to grant the permissions.
Permission | Required | Description |
android.permission.INTERNET | Yes | The android.permission.INTERNET permission is required to access the Internet. The SDK for Android must connect to the Internet to work. |
android.permission.ACCESS_NETWORK_STATE | No, but recommended | |
android.permission.CAMERA | Yes | The android.permission.CAMERA permission is required to access the camera. This permission is a dynamic permission in Android 6.0 and later. |
android.permission.READ_PHONE_STATE | No, but recommended | |
android.permission.READ_EXTERNAL_STORAGE | No, but recommended |
Download and configure the SDK
Download the Android SDK. The SDK consists of standard Android AAR packages.
Decompress the SDK package, copy all the AAR packages to the libs directory of your project, and then add the following dependencies to the build.gradle file of the project:
// SDK modules implementation files('libs/aliyun-identityplatform-xxx.aar') implementation files('libs/aliyun-identityface-xxx.aar') implementation files('libs/aliyun-identitycrypto-xxx.aar') implementation files('libs/aliyun-identityocr-xxx.aar') implementation files('libs/tygerservice-xxx.aar') implementation files('libs/Android-AliyunFaceGuard-xxx.aar') // SDK third-party dependency modules implementation 'com.android.support:appcompat-v7:28.0.0' implementation 'com.squareup.okhttp3:okhttp:3.11.0' implementation 'com.squareup.okio:okio:1.14.0' implementation 'com.aliyun.dpa:oss-android-sdk:+' implementation 'com.alibaba:fastjson:1.2.83_noneautotype'NoteIn the preceding code, xxx indicates the version number of the SDK.
The third-party dependencies are required for the SDK to properly work.
Usage notes
The SDK for Android provides the install, getMetaInfos, and verify methods.
install
Function prototype
public void install(Context context);Parameters
Parameter
Type
Description
context
Context
The context of the current application.
Return value: none.
getMetaInfos
Function prototype
public static String getMetaInfo(Context context);Parameters
Parameter
Type
Description
context
Context
The context of the current application.
Return value
The environment information of the current mobile device is returned in a JSON string. Example:
{
"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"
}verify
Function prototype
public void verify(String transactionId, Map<String, String> extParams, IdentityCallback callback);Parameters
Parameter
Type
Description
transactionId
String
The transactionId that is returned by the Initialize operation.
NoteYou can call the verify method only once by using a transactionId. You must obtain another transactionId before you call the verify method again.
extParams
Map<String, String>
The extended parameters. In most cases, set this parameter to NULL. For more information about the parameters that you can specify in extParams, see extParams.
callback
IdentityCallback
The callback method that is used to return the authentication result. 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
Key
Description
Example string
IdentityParams.OcrResultButtonColor
The color of the button at the bottom of the optical character recognition (OCR) result page.
"#FF0000"
IdentityParams.RoundProgressColor
The color of the progress circle for liveness detection.
"#FF0000"
IdentityParams.ShowBlbumIcon
Specifies whether to display the entry for uploading a photo from the album during document OCR. Valid values:
"1" (default): yes
"0": no
"1"
IdentityParams.ShowOcrResult
Specifies whether to display the OCR result screen during document OCR. Valid values:
"1" (default): yes
"0": no
"1"
IdentityParams.MaxErrorTimes
The maximum number of retries. Valid values: 3 to 10. Default value: 10.
"10"
IdentityParams.CardOcrTimeOutPeriod
The timeout period of document OCR. Valid values: 20 to 60. Default value: 20. Unit: seconds.
"20"
IdentityParams.FaceVerifyTimeOutPeriod
The timeout period of liveness detection. Valid values: 20 to 60. Default value: 20. Unit: seconds.
"20"
IdentityParams.OcrResultTimeOutPeriod
The timeout period for displaying the OCR result page. You can specify a custom timeout period. By default, the OCR result page does not time out.
"60"
IdentityParams.SdkLanguage
1. By default, the SDK supports the following languages:
"zh-Hans": simplified Chinese
"zh-Hant": traditional Chinese
"en": English
"ja": Japanese
"ko": Korean
"id": Indonesian
"ms": Malay
"th": Thai
"vi": Vietnamese
2. In addition to the preceding default languages, the SDK supports custom languages. For more information, see Add a language.
1. zh-Hans
2. Format of the value for specifying a custom language:
language-country
Return value: none.
Add a language
To add a custom language, perform the following steps:
Open your application project that integrates ID Verification client SDK.
Create a folder for the custom language and a string.xml file in the application project. In this example, Russian is added. Create the values-ru-rRU folder in the main module and add the string.xml file to the folder.
Translate the strings in the string.xml file to the language that you want to use. For more information, see Appendix 1.
Specify the custom language in your code. Format: language-country. In the following sample code, Russian is added.
Error codes
Error code | Description |
1000 | The authentication was successful. This result is for reference only. You can call the CheckResult operation to obtain the final authentication result. |
1001 | The authentication failed. You can call the CheckResult operation to query the detailed cause of the failure. |
1002 | A system error occurred. |
1003 | Failed to initialize the SDK. Check whether the time is correct on the client. |
1004 | A camera error occurred. You can perform the following steps to resolve the error:
|
1005 | A network error occurred. |
1006 | The user exits during the authentication. |
1007 | Invalid transactionId. |
1009 | Invalid client timestamp. |
1011 | Invalid document type. |
1012 | Key information is missing in the recognized document or the format is invalid. |
1013 | Poor image quality. |
1014 | The maximum number of errors is exceeded. |
1015 | Outdated Android version. |
1016 | No camera permission. |
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);
// Obtain metaInfo.
String metaInfo = IdentityPlatform.getMetaInfo(MainActivity.this);
/**
* Send metaInfo to the application server and call the Initialize operation to obtain the transactionId.
*/
// transactionId = getTransactionIdFromServer(metaInfo);
// Set the language of the SDK.
Map<String, String> extParams = new HashMap<>();
extParams.put(IdentityParams.SdkLanguage, "en");
// Start authentication.
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;
}
});
}
}Obfuscate configurations
-verbose
-keep class com.aliyun.identity.platform.api.** {*;}
-keep class com.aliyun.identity.IdentityUtils {*;}
-keep class com.aliyun.identity.ocr.IdentityOcrApi {*;}
-keep class com.aliyun.identity.platform.model.** {*;}
-keep class com.aliyun.identity.platform.config.** {*;}
-keep class com.aliyun.identity.face.IdentityFaceApi {*;}
-keep class com.face.verify.intl.** {*;}
-keep class com.alibaba.fastjson.** {*;}
-keep class net.security.device.api.** {*;}
-keep class face.security.device.api.** {*;}Demo
You can download the Demo for Android to experience the SDK.
Appendix 1
<string name="identity_aliyun_no_face">No face is detected.</string>
<string name="identity_aliyun_distance_too_far">Move closer.</string>
<string name="identity_aliyun_distance_too_close">Move further away.</string>
<string name="identity_aliyun_face_not_in_center">Move your face into the circle.</string>
<string name="identity_aliyun_bad_pitch">Directly face your mobile phone.</string>
<string name="identity_aliyun_bad_yaw">Directly face your mobile phone.</string>
<string name="identity_aliyun_is_moving">Make your face clearer.</string>
<string name="identity_aliyun_bad_brightness">Brighten up your face.</string>
<string name="identity_aliyun_bad_quality">Adjust your posture.</string>
<string name="identity_aliyun_bad_eye_openness">Directly face your mobile phone.</string>
<string name="identity_aliyun_blink_openness">Blink.</string>
<string name="identity_aliyun_stack_time">Stay still.</string>
<string name="identity_aliyun_is_blur">Make your face clearer.</string>
<string name="identity_aliyun_face_init_text">Directly face your mobile phone.</string>
<string name="identity_aliyun_face_comm_tips_text">Pick up your mobile phone and blink.</string>
<string name="identity_aliyun_zface_processing">Processing</string>
<string name="identity_message_box_title_not_support">The current system does not support facial recognition.</string>
<string name="identity_message_box_message_not_support">Only higher versions of the system support facial recognition.</string>
<string name="identity_message_box_title_no_camera_permission">Insufficient permissions.</string>
<string name="identity_message_box_message_no_camera_permission">Make sure that the application has been granted camera permissions.</string>
<string name="identity_message_box_title_operation_time_out">The operation timed out.</string>
<string name="identity_message_box_title_network">The network condition does not meet the requirements.</string>
<string name="identity_message_box_message_network">Check network connectivity.</string>
<string name="identity_message_box_title_sys_error">The operation failed.</string>
<string name="identity_message_box_message_sys_error">A system error occurred. Please try again.</string>
<string name="identity_message_box_title_exit_tip">Are you sure that you want to exit?</string>
<string name="identity_message_box_message_exit_tip">You need only to show your face.</string>
<string name="identity_message_box_btn_ok_tip">OK</string>
<string name="identity_message_box_btn_cancel_tip">Cancel</string>
<string name="identity_message_box_title_retry_face_scan">The operation timed out.</string>
<string name="identity_message_box_message_retry_face_scan">Directly face your mobile phone to make your face easier to scan.</string>
<string name="identity_message_box_btn_retry_ok">Try Again</string>
<string name="identity_message_box_title_retry_face_scan_time_out">The operation failed.</string>
<string name="identity_message_box_message_retry_face_scan_time_out">Facial recognition has been performed too frequently. Try again later.</string>
<string name="identity_message_box_message_btn_retry_ok_time_out">I Know</string>
<string name="identity_ocr_alert_net_message_error">The network condition does not meet the requirements. Please try again.</string>
<string name="identity_ocr_alert_retry_text">Retry</string>
<string name="identity_ocr_alert_exit_text">Exit</string>
<string name="identity_final_handleing">Verifying...</string>Appendix 2
Android language codes
The following table describes some Android language codes for reference.
Language | Language folder name | Language code |
| | |