Android接入 - ID Verification

ID Verification提供Android用戶端SDK，協助您在業務應用（App）中實現eKYC遠程身分識別驗證功能。您可通過服務端認證初始化介面，擷取唯一標識transactionId，並使用transactionId喚起用戶端SDK。本文結合範例程式碼介紹Android用戶端的接入流程。

使用限制

適用系統：Android 4.3及以上版本的手機或平板電腦。
不支援：x86架構裝置。

許可權說明

為提升安全效果，當前SDK需要以下許可權：

許可權	是否必須	說明
android.permission.INTERNET	是	連網許可權。Android SDK需要連網才能使用。
android.permission.ACCESS_NETWORK_STATE	否（推薦開啟）	連網許可權。Android SDK需要連網才能使用。
android.permission.CAMERA	是	網路攝影機許可權。該許可權在Android 6.0及以上版本屬於動態許可權。
android.permission.WRITE_EXTERNAL_STORAGE	否	引入`com.aliyun.dpa:oss-android-sdk:$version` 組件會自動聲明該許可權，如果接入的App不需要此許可權，可在`AndroidManifest.xml` 中使用remove標籤移除此許可權： `<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" tools:remove="true" />`

SDK下載和配置

Android SDK 為標準 AAR 包，請前往用戶端SDK發布記錄下載。如需體驗功能，可同步下載 Android Demo。

下載完畢之後解壓，將Android SDK檔案夾中的所有aar檔案拷貝到工程下的libs目錄中，並在工程的build.gradle檔案中添加如下依賴。

dependencies {
    // SDK modules 
    implementation files('libs/idv-identityplatform-xxx.aar') 
    implementation files('libs/idv-identityface-xxx.aar') 
    implementation files('libs/idv-identitycrypto-xxx.aar') 
    implementation files('libs/idv-identityocr-xxx.aar') 
    implementation files('libs/Android-AliyunFaceGuard-xxx.aar')
    implementation files('libs/idv-identitybase-sdk-xxx.aar') 
    implementation files('libs/idv-identityservice-sdk-xxx.aar') 
    implementation files('libs/idv-identityquality-sdk-xxx.aar') 
    implementation files('libs/idv-identityblink-sdk-xxx.aar')
    implementation files('libs/idv-identitymouth-sdk-xxx.aar') 

    implementation files('libs/idv-identitymnn-xxx.aar') 
    implementation files('libs/idv-identityocrservice-xxx.aar') 
    implementation files('libs/idv-identitynfc-xxx.aar') 
    implementation files('libs/IDOCR_PubSDK_Android-1.0.0.aar') 

    // 或者用fileTree 方式依賴指定IDVID Verification服務SDK AAR目錄，
    //implementation(fileTree(dir: "libs", includes: ["*.aar"]))

    implementation "androidx.appcompat:appcompat:1.5.0"
    implementation "androidx.activity:activity:1.7.0"
    implementation "androidx.recyclerview:recyclerview:1.0.0"
    implementation 'com.squareup.okhttp3:okhttp:4.9.3'
    implementation 'com.squareup.okio:okio:2.8.0'
    implementation 'com.aliyun.dpa:oss-android-sdk:2.9.21'
    implementation 'com.alibaba:fastjson:1.2.83_noneautotype'
}

說明

上述依賴中，xxx代表SDK的具體版本號碼。
使用中不能缺少三方依賴庫，否則會導致SDK功能異常。
從1.3.4版本開始，tygerservice-xxx.aar組件已被移除。
從1.3.6版本開始，新增idv-identitymouth-sdk-xxx.aar組件。

介面說明

Android SDK包含初始化SDK（install）、擷取MetaInfo（getMetaInfo）和開始認證（verify）介面。

初始化SDK（install）

函數原型

public void install(Context context);
public void install(Context context,Map<String, String> options);

參數說明

context：當前Application的context。

options：資訊採集可選項，預設可以為null。選擇性參數如下：

重要

ID Verification用戶端內建裝置助手安全模組，為了滿足不同地區資料收集合規要求，提供了不同的資料上報地區。您可以基於使用者屬性不同，設定CustomUrl和CustomHost指定不同的上報網站。
一次應用會話生命週期內只能指定一個地區上報，且服務端查詢時地區需要和上報地區保持一致。各產品服務端支援的地區有所不同，詳情請參考支援的地區。
各地區的CustomUrl：
- 中國香港：https://cloudauth-device.cn-hongkong.aliyuncs.com
- 新加坡：https://cloudauth-device.ap-southeast-1.aliyuncs.com
- 印尼（雅加達）：https://cloudauth-device.ap-southeast-5.aliyuncs.com
- 美國（矽谷）：https://cloudauth-device.us-west-1.aliyuncs.com
- 德國（法蘭克福）：https://cloudauth-device.eu-central-1.aliyuncs.com
- 馬來西亞（吉隆坡）：https://cloudauth-device.ap-southeast-3.aliyuncs.com

欄位名	說明	樣本
IPv6	是否使用IPv6網域名稱上報裝置資訊： 0（預設）：否（使用IPv4網域名稱） 1：是（使用IPv6網域名稱）	"1"
DataSwitch	裝置資訊上報時機。 0（預設）：初始化時 1：擷取Token時說明建議採用預設配置。	"1"
CustomUrl	設定資料上報伺服器網域名稱。	具體內容，請參見各地區的CustomUrl。
CustomHost	設定資料上報伺服器host。	"cloudauth-device.ap-southeast-1.aliyuncs.com" 說明此處為新加坡地區樣本，其他地區的host，請參見各地區的CustomUrl。

傳回值：無。

擷取MetaInfo （getMetaInfo）

函數原型

public static String getMetaInfo(Context context);

參數說明
名稱
類型
說明
context
Context
當前Application的context。

傳回值：String類型，以JSON字串格式返回當前行動裝置端的環境資訊：

{
  "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）

重要

調用此方法前，請確認您已將 MetaInfo 傳遞至服務端，並通過 Initialize 介面擷取了 transactionId 。
新版本新增protocol欄位返回，新增的protocol通過擴充參數extParams傳入。

函數原型

public void verify(String transactionId, Map<String, String> extParams, IdentityCallback callback);

參數說明

名稱	類型	說明
transactionId	String	從服務端初始化認證介面（Initialize）擷取的transactionId。重要每個transactionId只能調用一次verify函數，每次調用verify函數之前務必重新擷取transactionId。
extParams	Map<String, String>	擴充參數，通常情況下傳null即可。目前支援的自訂欄位，extParams配置說明在下方表格中列出。
callback	IdentityCallback	認證結果的回調介面，回調中的返回碼請參見Native SDK用戶端結果碼和結果子碼說明。回調定義如下： `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	說明	樣本（String類型）
IdentityParams.OcrResultButtonColor	OCR識別結果頁面的底部按鈕顏色。	#FF0000
IdentityParams.RoundProgressColor	掃臉時的圓圈顏色。	#FF0000
IdentityParams.ShowBlbumIcon	證件OCR識別環節，是否展示相簿上傳入口： 1（預設）：展示 0：不展示	1
IdentityParams.ShowOcrResult	證件OCR識別環節，是否展示識別結果頁： 1（預設）：展示 0：不展示	1
IdentityParams.EditOcrResult	證件OCR識別環節，識別結果頁是否可編輯： 1（預設）：可編輯 0：不可編輯	1
IdentityParams.MaxErrorTimes	重試次數上限。可設定範圍為3~10次，預設10次。	10
IdentityParams.CardOcrTimeOutPeriod	OCR識別環節逾時時間長度。可設定範圍為20~60秒，預設20秒。	20
IdentityParams.FaceVerifyTimeOutPeriod	活體採集檢測環節逾時時間長度。可設定範圍為20~60秒，預設20秒。	20
IdentityParams.OcrResultTimeOutPeriod	OCR識別結果頁面可編輯時間長度。可自訂配置，預設不限。	60
IdentityParams.SdkLanguage	SDK語言自訂設定。預設跟隨行動裝置系統的設定。說明 SDK具體支援的語言列表，請參見Android和iOS SDK 自訂語種。	zh-Hans
IdentityParams.CloseButtonLayout	關閉按鈕的布局： left（預設）：左側 right：右側	left
IdentityParams.WaterMark	OCR識別成功後浮水印文字。	測試浮水印文字
IdentityParams.Protocol	SDK Protocol。說明通過服務端Initialize介面擷取protocol，傳入擴充參數中，可減少SDK內部介面互動，提升網路體驗。	無

結果碼

返回的結果碼與結果字碼資訊，請參見Native SDK用戶端結果碼和結果子碼說明。

範例程式碼

public class MainActivity extends AppCompatActivity {
    private String transactionId = "";
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
    
        // 初始化SDK
        IdentityPlatform.getInstance().install(MainActivity.this);
    
        // 擷取MetaInfo
        String metaInfo = IdentityPlatform.getMetaInfo(MainActivity.this);
    
        /**
         * 將MetaInfo發送到App伺服器端，調用雲端Initialize介面擷取transactionId，
         * 新版本會返回protocol資料
         */
        // transactionId = getTransactionIdFromServer(metaInfo).transactionId;
        //protocol ==getTransactionIdFromServer(metaInfo).protocol;;
        
        Map<String, String> extParams = new HashMap();
        //設定協議資料
        extParams.put(IdentityParams.PROTOCOL, protocol);
        // 設定SDK語言
        extParams.put(IdentityParams.SdkLanguage, "en");
        // 開始認證
        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;
                    }
                });
    }
    
}

混淆配置

-verbose
-keep class com.idv.identity.platform.api.** {*;}
-keep class com.idv.identity.platform.log.** {*;}
-keep class com.idv.identity.util.IdentityUtils {*;}
-keep class com.idv.identity.ocr.IdentityOcrApi {*;}
-keep class com.idv.identity.platform.model.** {*;}
-keep class com.idv.identity.platform.config.** {*;}
-keep class com.idv.identity.face.IdentityFaceApi {*;}


-keep class com.face.verify.intl.** {*;}
-keep class com.alibaba.fastjson.** {*;}
-keep class face.security.device.api.** {*;}
-keep class net.security.device.api.** {*;}
-keep class com.dtf.toyger.** { *; }
-dontwarn net.security.device.api.**
-dontwarn face.security.device.api.**


-keep class com.idv.identity.service.algorithm.** {*;}
-keep class com.idv.identity.base.algorithm.** {*;}
-keep class com.idv.identity.quality.QualityRouter {*;}
-keep class com.idv.identity.blink.BlinkRouter {*;}
-keep class com.idv.identity.service.IdentityFaceService {*;}
-keep class com.idv.identity.service.ocr.IdentityDocService {*;}
-keep class com.idv.identity.mouth.MouthRouter {*;}

-keep class com.alibaba.sdk.android.oss.** { *; }
-dontwarn okio.**
-dontwarn org.apache.commons.codec.binary.**



# NFC
-keep class com.idv.identity.nfc.IdentityNfcApi { *; }
-keep class org.jmrtd.** {*;}
-keep class net.sf.**{*;}
-keep class org.**{*;}
-keep class cn.**{*;}


# Please add these rules to your existing keep rules in order to suppress warnings.
# This is generated automatically by the Android Gradle plugin.
-dontwarn com.fasterxml.**
-dontwarn com.google.**
-dontwarn java.applet.Applet
-dontwarn java.awt.**
-dontwarn javax.**
-dontwarn org.**
-dontwarn retrofit2.**
-dontwarn springfox.documentation.spring.web.json.Json

#日誌混淆，可選
-assumenosideeffects class android.util.Log {
    public static *** d(...);
}

# 若使用的1.3.2之前的版本需要添加如下混淆規則
-keepattributes Signature
-keepattributes *Annotation*
-keep class com.alibaba.fastjson.** { *; }
-keep class * extends com.alibaba.fastjson.TypeReference { *; }

組件裁剪

在 SDK 接入階段，支援對部分組件進行裁剪。在確保功能完整與安全合規的前提下，建議依據實際產品方案按需整合組件，以最大程度減小 SDK 包體積。詳細的裁剪規則，請參見SDK裁剪說明。

名稱	類型	說明
context	Context	當前Application的context。