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.
Permission | Required | Description |
android.permission.INTERNET | Yes | The permission 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 permission required to access the camera. The permission is dynamically granted 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 SDK for Android. The SDK consists of standard Android Archive (AAR) packages.
Decompress the SDK package, copy all AAR packages of the SDK 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 'androidx.appcompat:appcompat:1.1.0' implementation 'com.squareup.okhttp3:okhttp:3.11.0' implementation 'com.squareup.okio:okio:2.2.2' implementation 'com.aliyun.dpa:oss-android-sdk:2.9.4' implementation 'com.alibaba:fastjson:1.1.72.android'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 API operations.
install
Function prototype
public void install(Context context);Parameters
Parameter
Type
Description
context
Context
The context of the current app.
Return value: none.
getMetaInfo
Function prototype
public static String getMetaInfo(Context context);Parameters
Parameter
Type
Description
context
Context
The context of the current app.
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 transaction ID that is returned by the Initialize operation.
NoteYou can call the verify function only once by using a transaction ID. You must obtain another transaction ID before you call the verify function 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 the extParams section of this topic.
callback
IdentityCallback
The callback function that is used to return the verification 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 value (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 page during document OCR. Valid values:
1 (default): yes.
0: no.
1
IdentityParams.MaxErrorTimes
The maximum number of retries that are allowed.
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
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.
NoteIn addition to the preceding default languages, the SDK supports custom languages. For more information, see Add a language.
zh-Hans
CloseButtonLayout
The position of the button that you can click to stop the SDK. Valid values:
left (default)
right
left
Return value: none.
Add a language
To add a custom language, perform the following steps:
Open your app project that integrates ID Verification client SDK.
Create a folder for the custom language and a string.xml file in the app project. In this example, Russian is added. Create the values-ru-rRU folder in the project of the main module and create the string.xml file in 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 | Billed | Description |
1000 | Yes | The customer completed the face verification process, and the verification result was successful. This result is for reference only. You can call the CheckResult operation to obtain the final verification result and proceed to the next step. |
1001 | Yes | The customer completed the face verification process, and the verification result was failed. This result is for reference only. You can call the CheckResult operation to obtain the final verification result and the detailed cause of the failure, and then proceed to the next step. |
1002 | No | A system error occurred. |
1003 | No | The SDK failed to be initialized. Check whether the client time is valid. |
1004 | No | A camera error occurred. To fix the error, perform the following operations:
|
1005 | No | A network error occurred. |
1006 | No | The customer unexpectedly exited. |
1007 | No | The transaction ID is invalid. |
1009 | No | The timestamp of the client is invalid. |
1011 | No | The specified document type does not match the submitted document. |
1012 | No | The critical information is missing after document verification or the format verification failed. |
1013 | No | The image quality does not meet the requirements. |
1014 | No | The number of errors exceeds the upper limit. |
1015 | No | The Android system version is excessively early. |
1016 | No | The camera permissions are not obtained. |
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 app server and call the Initialize operation to obtain a transaction ID.
*/
// transactionId = getTransactionIdFromServer(metaInfo);
// Specify the language of the SDK.
Map<String, String> extParams = new HashMap<>();
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;
}
});
}
}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.** {*;}
-keep class com.dtf.toyger.** {*;}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 face verification.</string>
<string name="identity_message_box_message_not_support">Only higher versions of the system support face verification.</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 app 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. 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 to only 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">The number of face verification failures exceeds the upper limit. Try again later.</string>
<string name="identity_message_box_message_btn_retry_ok_time_out">OK.</string>
<string name="identity_ocr_alert_net_message_error">The network condition does not meet the requirements. 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 lists some Android language codes for reference.
Language | Language folder name | Language code |
| | |