ID Verification：Android接入

1. 初始化（initWithOptions）

SDK 內部初始化，在 App 啟動的時候，您需要儘可能早地調用該函數 。請參考接入流程，在[時機1]調用初始化 initWithOptions 介面。

• 函數原型

  public void initWithOptions(Context ctx, 
                         String userProductKey,
                         Map<String, String> options,
                         FaceSecInitListener securityInitListener);

• 參數說明

  • ctx：當前 Application Context，或 Activity Context。

  • userProductKey：用於標識使用者身份，阿里雲分配的產品 AppKey（不同於AK），請聯絡商務經理擷取。

    重要

    整合FACE_GUARD的應用，依賴業務側具備成熟的Face Service演算法和風險策略營運體系。建議您可以先和商務經理溝通評估業務情境匹配程度。

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

    說明

    • ID Verification用戶端內建裝置助手安全模組，為了滿足不同地區資料收集合規要求，提供了不同的資料上報地區。您可以基於使用者屬性不同，設定CustomUrl和CustomHost指定不同的上報網站。

      注意：一次應用會話生命週期內只能指定一個地區上報，且服務端查詢時地區需要和上報地區保持一致。

    • 指定網站上報：

      • 新加坡網站（預設）：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.cn-hongkong.aliyuncs.com

    • 不同產品服務端支援的地區，參考：支援的地區。

    欄位名	說明	樣本
    IPv6	是否使用IPv6網域名稱上報裝置資訊： 0（預設）：否（使用IPv4網域名稱） 1：是（使用IPv6網域名稱）	"1"
    DataSwitch	裝置資訊上報時機。 0（預設）：初始化時 1：擷取Token時 說明 建議採用預設配置。	"1"
    CustomUrl	設定資料上報伺服器網域名稱。	"https://cloudauth-device.ap-southeast-1.aliyuncs.com"
    CustomHost	設定資料上報伺服器host。	"cloudauth-device.ap-southeast-1.aliyuncs.com

  • securityInitListener：初始化回調監聽介面，可在回調中判斷初始化是否成功， 預設可以傳入null。其中，code 欄位取值範圍可參考code 傳回值。

    securityInitListener定義

    public interface FaceSecInitListener {
        // code表示介面調用狀態代碼
        void onInitFinish(int code);
    }

• 調用樣本

  public class CustomApplication extends Application {
      private static String USER_PRODUCT_KEY = "123e4567e89b12d3a45642661417****";
  
      @Override
      public void onCreate() {
          super.onCreate();
  
          Map<String, String> options = new HashMap<>();
          options.put("IPv6", "0"); // 設定為IPv4
          options.put("DataSwitch", "0"); // 設定為初始化階段採集
          // options.put("DataType", String.valueOf(NO_EXTRA_DEVICE_DATA)); 設定合規採集
          // 設定自訂的資料上報地區
          // options.put("CustomUrl", "xxx"); 設定上報網站Url
          // options.put("CustomHost", "xxx"); 設定上報網站Host
  
          // 標準調用(推薦)
          FaceSecDevice.getInstance().initWithOptions(this, USER_PRODUCT_KEY, 
                                                      options, null);
  
          // 回調調用
          FaceSecDevice.getInstance().initWithOptions(this, USER_PRODUCT_KEY,
                                        options, new FaceSecInitListener() {
                @Override
                public void onInitFinish(int code) {
                    if (FaceSecCode.SC_SUCCESS != code) {
                        Log.d("AliyunFaceGuard", "初始化失敗");
                    } else {
                        Log.d("AliyunFaceGuard", "初始化成功");
                    }
                }
            });
      }
  }

2. 擷取用戶端 token（getDeviceToken）

擷取用戶端 token，請參考接入流程在[時機2]進行調用，並上報到業務自己的伺服器，後續通過伺服器端查詢FACE_GUARD的FaceGuardRisk介面，從而擷取用戶端裝置風險識別資訊。

• 函數原型

  public SecurityToken getDeviceToken() 
  // 推薦傳入bizId
  public SecurityToken getDeviceToken(String bizId)

• 參數

  bizId：客戶的業務ID，可用於關聯業務ID和token。預設情況可以不傳。

• 傳回值

  • FaceSecToken 類型，定義如下：

    public class FaceSecToken {
        // 介面調用狀態代碼
        public int code;
        
        // 用於伺服器端查詢結果的token字串。
        public String token;
    }

  • code：返回介面調用狀態代碼，可用於判斷介面調用是否成功。

    code傳回值

    FaceSecCode	Code	備忘
    SC_SUCCESS	10000	SDK初始化成功。
    SC_NOT_INIT	10001	SDK未初始化。
    SC_NOT_PERMISSION	10002	SDK需要的Android基礎許可權未完全授權。
    SC_UNKNOWN_ERROR	10003	系統未知錯誤。
    SC_NETWORK_ERROR	10004	網路錯誤。
    SC_NETWORK_ERROR_EMPTY	10005	網路錯誤，返回內容為空白串。
    SC_NETWORK_ERROR_INVALID	10006	網路返回的格式非法。
    SC_PARSE_SRV_CFG_ERROR	10007	服務端配置解析失敗。
    SC_NETWORK_RET_CODE_ERROR	10008	網關返回失敗。
    SC_APPKEY_EMPTY	10009	AppKey為空白。
    SC_PARAMS_ERROR	10010	其他參數錯誤。
    SC_FGKEY_ERROR	10011	密鑰計算錯誤。
    SC_APPKEY_ERROR	10012	APPKey 無效。

  • token：返回 token 字串資訊，商務就緒後續查詢阿里雲FACE_GUARD介面。

    重要

    token 字串在網路環境良好的情境下，長度為 600 位元組左右；在網路環境較差的情境下，返回的長度在 2.5K 左右，並且帶有特殊標識：

    • 有網："U0dfTkxxxx"

    • 弱網："U0dfUFxxxx"

    如果業務上出現了大量的長 token：

    • 首先，請確保用戶端的網路是暢通的；

    • 其次，請參考接入流程進行接入，在[時機1]調用初始化 initWithOptions 介面，在[時機2]調用 getDeviceToken 介面；或確保 SDK 的 initWithOptions 介面和 getDeviceToken 介面調用間隔在 3 秒以上。

• 調用樣本

  new Thread() {
      @Override
      public void run() {
          // 推薦傳入bizId，防止deviceToken被篡改。
          String bizId = "1234567890abcdef1234567890ab****";
          FaceSecToken deviceToken = FaceSecDevice.getInstance().getDeviceToken(bizId);
          if(null != deviceToken){
              if(FaceSecCode.SC_SUCCESS == deviceToken.code){
                  Log.d("AliyunFace", "token: " + deviceToken.token);
              } else {
                  Log.e("AliyunFace", "getDeviceToken error, code: " + deviceToken.code);
              }
          } else {
              Log.e("AliyunFace", "getDeviceToken is null.");
          }
      }
  }.start();

3. 攜帶token請求服務端

成功擷取deviceToken（FaceSecToken.token）後，可攜帶此參數請求商務服務器，由服務端查詢並校正結果。具體操作，請參見服務端API介面。