Android integration
The Financial-grade NFC Authentication service provides an Android client SDK to help you implement NFC authentication features in your business application. This topic describes the integration process for the Android client and provides sample code.
Limitations
Debugging in a simulator is not supported.
The SDK is supported only on NFC-capable smartphones and tablets running Android 4.4 or later.
Permissions
Permission | Required | Description |
android.permission.INTERNET | Yes | Required for the SDK to access the internet. |
android.permission.ACCESS_NETWORK_STATE | Yes | |
android.permission.NFC | Yes | Required to read NFC tags. |
Dependency configuration
Download the Android client SDK.
Decompress the downloaded package, copy all AAR files from the Android client SDK folder to the
app/libsdirectory in your project. Then, add the following dependencies to your project'sbuild.gradlefile.ImportantIn the sample code,
xxxrepresents the version number. Replace it with the actual version number from the AAR file name in your downloaded Android client SDK package.# Alibaba Cloud Real Person Authentication service SDK AAR implementation files('libs/aliyun-facade-xxx.aar') implementation files('libs/aliyun-base-xxx.aar') implementation files('libs/aliyun-nfc-xxx.aar') # Required third-party dependencies for the Alibaba Cloud Real Person Authentication service. Do not omit them. implementation 'com.squareup.okhttp3:okhttp:3.11.0' implementation 'com.squareup.okio:okio:1.14.0' implementation 'com.alibaba:fastjson:1.2.83_noneautotype'
API reference
The Android SDK includes three main APIs: install to initialize the SDK, getMetaInfos to get environment information, and verify to start the authentication process.
Initialize the SDK
Initializes the SDK. We recommend using lazy initialization, meaning you should initialize the SDK only after the user agrees to the Privacy Policy and enters a workflow that requires face recognition.
Method signature:
public static void install(Context context);To initialize the SDK in an IPv6 network, use the following code:
public static int installIPv6(Context context)Parameters:
Parameter
Type
Description
context
Context
The application context.
Return value: None.
Get MetaInfos
Gets the mobile client environment information. You must send this information to your app server, which then uses it as the
MetaInfosparameter when calling the server-side InitFaceVerify API to obtain aCertifyIdfor subsequent authentication steps.
Method signature:
public static String getMetaInfos(Context context);Parameters:
Parameter
Type
Description
context
Context
The context of the current application.
Return value: A JSON-formatted string that contains the mobile device's environment information. The following is a sample return value:
{"deviceType":"android","appVersion":"1.0","osVersion":"11","appName":"com.aliyun.aliyunfaceDemo","nfcSupport":"Y","bioMetaInfo":"7.0.0:393216,0","deviceModel":"M2011K2C","sdkVersion":"2.2.8.1","zimVer":"1.0.0","voiceSdkVersion":"1.0.0"}
Start verification
Starts the real person authentication process.
Method signature:
public void verify(final String certifyId, boolean useMsgBox, HashMap<String, String> extParams, ZIMCallback callback);Parameters:
Parameter
Type
Description
certifyId
String
The CertifyId obtained from the server-side initialization API (InitFaceVerify-Initiate NFC Authentication Request).
NoteEach CertifyId can only be used to call the
verifyAPI once. You must obtain a new CertifyId before each call toverify.useMsgBox
boolean
Specifies whether the SDK displays its built-in dialog box for exceptions that occur during verification. Valid values:
true: The SDK displays a dialog box. After the user confirms, the error code is returned.
false: The SDK does not display a dialog box and returns the error code directly.
You can decide how to present messages based on the design of your business application.
extParams
HashMap<String, String>
Custom parameters. You can typically pass
null. To set the UI language, you can either change the system language or add theext_params_key_languageFromAppkey to extParams. Valid language values are:en: English
zh-CN: Simplified Chinese
Other values are not supported.
The following is a sample call:
ZIMFacade zimFacade = ZIMFacadeBuilder.create(MainActivity.this); extParams.put("ext_params_key_languageFromApp", "zh-CN"); zimFacade.verify(certifyId,useMsgBox,extParams,callback);callback
ZIMCallback
The callback for the verification result:
public interface ZIMCallback { boolean response(ZIMResponse response); }For the definition of the
ZIMResponseclass, see Verification result and error codes.Return value: None.
Verification result and error codes
The verification result is returned in a ZIMResponse object, which is defined as follows:
public class ZIMResponse {
/**
* Result code
*/
public int code;
/**
* Reason for the result
*/
public String reason;
// ......
}Error code | Error message | Description |
1000 | Face verification successful | The user completed the face verification process. The recommended authentication result is 'pass'. This result is for reference only. Call the server-side DescribeFaceVerify API to get the final authentication result. |
1001 | System error | A system error occurred. |
1003 | Verification interrupted | The verification process was interrupted. |
2002 | Network error | A network error occurred. |
2003 | Client-side device time error | The time on the client-side device is incorrect. |
2006 | Failed to submit authentication data, or face verification failed. | This result is for reference only. Call the server-side DescribeFaceVerify API to get the final authentication result and the specific reason for the failure. |
Complete result encoding information (Click to view)
Obfuscation configuration
To prevent obfuscation from breaking SDK functionality, add the following rules to the proguard-rules.pro file in your app project:
-keep class com.alipay.deviceid.** { *; }
-keep class net.security.device.api.** {*;}
-keep class org.json.** { *;}
-keep class com.alibaba.fastjson.** {*;}
-dontwarn okio.**
-dontwarn org.apache.commons.codec.binary.**
-keepclassmembers,allowobfuscation class * {
@com.alibaba.fastjson.annotation.JSONField <fields>;
}Sample code
import android.app.Activity;
import android.content.Context;
import android.os.Bundle;
import android.util.Log;
import com.alipay.face.api.ZIMCallback;
import com.alipay.face.api.ZIMFacade;
import com.alipay.face.api.ZIMFacadeBuilder;
import com.alipay.face.api.ZIMResponse;
public class MainActivity extends Activity {
private String certifyId = "xxx";
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
Context ctx = getApplicationContext();
// Initialize the SDK.
ZIMFacade.install(ctx);
// Get MetaInfos.
String metaInfos = ZIMFacade.getMetaInfos(ctx);
// Send MetaInfos to your app server and call the server-side InitFaceVerify API to obtain the CertifyId.
// certifyId = getCertifyIdFromServer(metaInfo); // You must implement this part.
// Start verification.
ZIMFacade zimFacade = ZIMFacadeBuilder.create(ctx);
zimFacade.verify(certifyId, true, null, new ZIMCallback() {
@Override
public boolean response(final ZIMResponse response) {
if (1000 == response.code) {
Log.d("AliyunFace", "Verification successful.");
} else {
Log.e("AliyunFace", "Verification failed.");
}
return true;
}
});
}
}Demo package
For parallel front-end and back-end development, you can download the demo package to quickly try out the features:
You can obtain the CertifyId by following the steps in the Start verification section.
Upgrade notes
If you are upgrading from the Financial-grade Real Person Authentication solution to Financial-grade NFC Authentication, update the AAR packages and configuration files in your project.
SDK package size clipping
For more information, see SDK package clipping.