Android integration

Updated at:

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

  1. Download the Android client SDK.

  2. Decompress the downloaded package, copy all AAR files from the Android client SDK folder to the app/libs directory in your project. Then, add the following dependencies to your project's build.gradle file.

    Important

    In the sample code, xxx represents 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 MetaInfos parameter when calling the server-side InitFaceVerify API to obtain a CertifyId for 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).

    Note

    Each CertifyId can only be used to call the verify API once. You must obtain a new CertifyId before each call to verify.

    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 the ext_params_key_languageFromApp key 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 ZIMResponse class, 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)

Error code

Description

1000

Z5120 - Authentication passed. Call the server-side query API to retrieve detailed authentication information.

1001

Z1000 - Other errors.

Z1003 - Unsupported CPU architecture.

Z1004 - The Android system version is too low.

Z1024 - The SDK authentication flow is in progress. Wait for the local authentication flow to complete before initiating a new call.

Z1035 - The context is empty.

Z1036 - The install() method was not called to complete initialization before authentication.

Z1037 - The CertifyId is null or empty.

Z7001 - A data error occurred during SDK initialization or use.

Z3001 - NFC retry limit exceeded.

Z3002 - The request to enable the system NFC feature was denied.

Z3003 - The device does not support NFC.

Z3004 - An error related to the NFC protocol occurred.

Z3005 - The three elements for pass-through mode are incorrect.

1003

Z1008 - The user canceled the authentication process.

Z1009 - The user clicked "Do not grant" on the authorization page.

2002

Z1011 - A network error occurred during client initialization.

Z1012 - A client-side network access error occurred.

Z1025 - The client initialization API returned a network error.

Z1026 - A network error occurred during the information upload.

Z1027 - A network error was returned by the server-side authentication API.

2003

The client device time is incorrect.

2006

Z5128 - Authentication failed. Call the server-side query API to retrieve the specific reason for the failure.

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:

Android sample code

Note

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.