All Products
Search
Document Center

ID Verification:Android

Last Updated:Feb 20, 2024

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

  1. Download the SDK for Android. The SDK consists of standard Android AAR packages.

  2. 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'
    Note
    • In the preceding code, xxx indicates the version number of the SDK.

    • The third-party dependencies are required for the SDK to properly work.

Methods

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.

    Note

    You 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": yes. This is the default value.

    • "0": no.

    "1"

    IdentityParams.ShowOcrResult

    Specifies whether to display the OCR result screen during document OCR. Valid values:

    • "1": yes. This is the default value.

    • "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:

  1. Open your application project that integrates ID Verification client SDK.

  2. 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.

image.png

  1. Translate the strings in the string.xml file to the language that you want to use. For more information, see Appendix 1.

  2. Specify the custom language in your code. Format: language-country. In the following sample code, Russian is added.

image.png

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:

  1. Before you perform authentication, make sure that the application has the camera permission.

  2. If the error persists, clear the cache of the application and try again.

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

Afrikaans (South Africa)
Albanian (Albania)
Arabic (Algeria)
Arabic (Bahrain)
Arabic (Egypt)
Arabic (Iraq)
Arabic (Jordan)
Arabic (Kuwait)
Arabic (Lebanon)
Arabic (Libya)
Arabic (Morocco)
Arabic (Oman)
Arabic (Qatar)
Basque (Spain)
Belarusian (Belarus)
Bulgarian (Bulgaria)
Catalan (Spain)
Simplified Chinese (Chinese mainland)
Traditional Chinese (Hong Kong, China)
Traditional Chinese (Taiwan, China)
Chinese (Macao, China)
Chinese (Singapore)
Croatian (Croatia)
Czech (Czech Republic)
Danish (Denmark)
Divehi (Maldives)
Dutch (Belgium)
Dutch (Netherlands)
English (Australia)
English (Canada)
English (South Africa)
English (Republic of the Philippines)
English (New Zealand)
English (United Kingdom)
English (United States)
Farsi (Iran)
Finnish (Finland)
French (France)
French (Belgium)
French (Monaco)
French (Switzerland)
Galician (Spain)
Georgian (Georgia)
German (Germany)
German (Luxembourg)
German (Switzerland)
Greek (Greece)
Gujarati (India)
Hebrew (Israel)
Hindi (India)
Hungarian (Hungary)
Icelandic (Iceland)
Italian (Italy)
Japanese (Japan)
Kazakh (Kazakhstan)
Kannada (India)
Korean (Korea)
Latvian (Latvia)
Lithuanian (Lithuania)
Malay (Brunei Darussalam)
Malay (Malaysia)
Marathi (India)
Mongolian (Mongolia)
Norwegian (Nynorsk) (Norway)
Polish (Poland)
Portuguese (Brazil)
Portuguese (Portugal)
Romanian (Romania)
Sanskrit (India)
Russian (Russia)
Slovak (Slovakia)
Spanish (Argentina)
Spanish (Spain)
Swedish (Sweden)
Thai (Thailand)
Turkish (Turkey)
Ukrainian (Ukraine)
Urdu (Islamic Republic of Pakistan)
Vietnamese (Vietnam)

values-af-rZA
values-sq-rAL
values-ar-rDZ
values-ar-rBH
values-ar-rEG
values-ar-rIQ
values-ar-rJO
values-ar-rKW
values-ar-rLB
values-ar-rLY
values-ar-rMA
values-ar-rOM
values-ar-rQA
values-eu-rES
values-be-rBY
values-bg-rBG
values-ca-rES
values-zh-rCN
values-zh-rHK
values-zh-rTW
values-zh-rMO
values-zh-rSG
values-hr-rHR
values-cs-rCZ
values-da-rDK
values-div-rMV
values-nl-rBE
values-nl-rNL
values-en-rAU
values-en-rCA
values-en-rZA
values-en-rPH
values-en-rNZ
values-en-rGB
values-en-rUS
values-fa-rIR
values-fi-rFI
values-fr-rFR
values-fr-rBE
values-fr-rMC
values-fr-rCH
values-gl-rES
values-ka-rGE
values-de-rDE
values-de-rLU
values-de-rCH
values-el-rGR
values-gu-rIN
values-he-rIL
values-hi-rIN
values-hu-rHU
values-is-rIS
values-it-rIT
values-ja-rJP
values-kk-rKZ
values-kn-rIN
values-ko-rKR
values-lv-rLV
values-lt-rLT
values-ms-rBN
values-ms-rMY
values-mr-rIN
values-mn-rMN
values-nn-rNO
values-pl-rPL
values-pt-rBR
values-pt-rPT
values-ro-rRO
values-sa-rIN
values-ru-rRU
values-sk-rSK
values-es-rAR
values-es-rES
values-sv-rSE
values-th-rTH
values-tr-rTR
values-uk-rUA
values-ur-rPK
values-vi-rVN

af-ZA
sq-AL
ar-DZ
ar-BH
ar-EG
ar-IQ
ar-JO
ar-KW
ar-LB
ar-LY
ar-MA
ar-OM
ar-QA
eu-ES
be-BY
bg-BG
ca-ES
zh-CN
zh-HK
zh-TW
zh-MO
zh-SG
hr-HR
cs-CZ
da-DK
div-MV
nl-BE
nl-NL
en-AU
en-CA
en-ZA
en-PH
en-NZ
en-GB
en-US
fa-IR
fi-FI
fr-FR
fr-BE
fr-MC
fr-CH
gl-ES
ka-GE
de-DE
de-LU
de-CH
el-GR
gu-IN
he-IL
hi-IN
hu-HU
is-IS
it-IT
ja-JP
kk-KZ
kn-IN
ko-KR
lv-LV
lt-LT
ms-BN
ms-MY
mr-IN
mn-MN
nn-NO
pl-PL
pt-BR
pt-PT
ro-RO
sa-IN
ru-RU
sk-SK
es-AR
es-ES
sv-SE
th-TH
tr-TR
uk-UA
ur-PK
vi-VN