通過FACE_GUARD SDK在HarmonyOS上啟用面部驗證 - ID Verification

本文介紹FACE_GUARD的Harmony端接入流程。

使用須知

重要

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

Harmony SDK使用限制如下：

不支援模擬器模式調試。
Harmony Next （0.0.71）及以上版本，API版本最低支援12。
僅支援開啟位元組碼加密方案。

接入步驟

前期準備

接入前需要進行許可權配置和SDK依賴配置，您可以參考下面的步驟操作。

許可權說明

為增強人臉作弊的識別效果，當前 SDK 需要以下許可權：

許可權	是否必須	說明
ohos.permission.INTERNET	是	連網許可權。SDK需要連網才能使用。
ohos.permission.GET_NETWORK_INFO	是	網路狀態確認。SDK可以根據網路狀態提供更好的服務。
ohos.permission.STORE_PERSISTENT_DATA	否（推薦賦予）	允許應用儲存持久化的資料。SDK可以增加裝置指紋穩定性

依賴配置

下載 Harmony SDK（請聯絡商務經理擷取），並解壓。SDK 為 Harmony 標準的 .har 包。
將.har檔案拷貝到工程中存放har包的目錄。建議參考鴻蒙官方文檔放至libs目錄下，在工程根目錄的oh-package.json5添加認證包的版本依賴樹管理，並修改版本號碼，樣本如下：
```
{
  ....
  "dependencies": {
    "aliyunfaceguard": "file:./libs/AliyunFaceGuard-xxx.har"
    ....
  }
}
```

介面混淆配置（重要）

為避免介面被混淆而造成功能異常，請查看.har包中obfuscation.txt檔案中的配置，請勿移除該檔案。

若在部分版本編譯器發現混淆配置無法合并，導致正常無法接入，需要在應用的主工程打包添加.har包中的混淆設定檔 obfuscation-rules.txt ，並將混淆配置添加當前工程中。

調用SDK

前期準備完成後，可按照下面三個步驟完成用戶端接入。

初始化（initWithOptions）
擷取用戶端token（getDeviceToken）
攜帶Token請求服務端

1. 初始化（initWithOptions）

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

重要

多線程情境下初始化介面需要在主線程調用，且應用的生命週期內只需要調用1次。

函數原型

  public initWithOptions(ctx: Context, userProductKey: string,
                         options: Map<string, string>,
                         securityInitListener: SecurityInitListener): void

參數說明

ctx：當前 UIContext 或 Context ，可使用 getContext() 方法擷取。
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表示介面調用狀態代碼
    onInitFinish: (code: number) => void;
}
```

調用樣本

@State USER_PRODUCT_KEY: string = "123e4567e89b12d3a45642661417****";

let options: Map<string, string> = new Map<string, string>();
options.set("IPv6", "0"); // 設定為IPv4
options.set("DataSwitch", "0"); // 設定為初始化階段採集
// 設定自訂的資料上報地區
// options.set("CustomUrl", "xxx"); 設定上報網站Url
// options.set("CustomHost", "xxx"); 設定上報網站Host

// 標準調用(推薦)
FaceSecDevice.getInstance().initWithOptions(getContext(), 
                            this.USER_PRODUCT_KEY, options, null);

// 回調調用
FaceSecDevice.getInstance().initWithOptions(this.context, 
                            this.USER_PRODUCT_KEY, options, {
    onInitFinish(code: number) {
      if (FaceSecCode.SC_SUCCESS != code) {
        console.log("AliyunFaceGuard 初始化失敗");
      } else {
        console.log("AliyunFaceGuard 初始化成功");
      }
    }
});

2. 擷取用戶端token（getDeviceToken）

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

重要

請參考接入流程進行接入，在[時機1]()調用初始化 initWithOptions 介面，在[時機2]()調用 getDeviceToken 介面；或確保 initWithOptions 介面和 getDeviceToken 介面調用時間間隔 3 秒以上。
調用 getDeviceToken 時建議傳入 bizId，可以將本次 token 和業務唯一認證 ID 綁定，後在服務端查詢結果時將 ID 一起傳入，並確保用戶端傳入bizId和服務端傳入 ID 一致，可避免 Token 被篡改的風險。
建議在 APP 子線程程上調用 getDeviceToken 介面，以避免介面調用耗時可能導致的崩潰。

函數原型

// 推薦傳入bizId
public getDeviceToken(bizId?: string): SecurityToken

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

傳回值

FaceSecToken 類型，屬性如下：

public class FaceSecToken {
    // 介面調用狀態代碼
    public code: number = 0;

    // 用於伺服器端查詢結果的token字串。
    public token: string = "";
}

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的FaceGuardRisk介面。
重要
token 字串在網路環境良好的情境下，長度為 600 位元組左右；在網路環境較差的情境下，返回的長度在 2.5K 左右，並且帶有特殊標識：
- 有網："U0dfTkxxxx"
- 弱網："U0dfUFxxxx"
如果業務上出現了大量的長 token：
- 首先，請確保用戶端的網路是暢通的；
- 其次，請參考接入流程進行接入，在[時機1]調用初始化 initWithOptions 介面，在[時機2]調用 getDeviceToken 介面；或確保 SDK 的 initWithOptions 介面和 getDeviceToken 介面調用間隔在 3 秒以上。

調用樣本

// 傳入bizId樣本，bizId為客戶的業務ID，可以選擇是否傳入。
let bizId = "1234567890abcdef1234567890ab****"
let tokenObj: FaceSecToken = FaceSecDevice.getInstance().getDeviceToken(bizId);
if (tokenObj.code == FaceSecCode.SC_SUCCESS) {
  console.log("Aliyun Token: " + tokenObj.token);
} else {
  console.log("Aliyun Code: " + tokenObj.code);
}

3. 攜帶Token請求服務端

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

完整程式碼範例

import { FaceSecCode, FaceSecToken, FaceSecDevice } from 'aliyunfaceguard';

@Entry
@Component
struct Index {
  @State message: string = 'AliyunFaceGuard';
  @State USER_PRODUCT_KEY: string = "<請聯絡商務經理擷取>";

  build() {
    Row() {
      Column() {
        Button(this.message)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .onClick((event: ClickEvent) => {
            // 初始化SDK
            // 在App生命週期中只需要調用1次
            // 建議在接入流程時機1調用initWithOptions介面
            this.doInit();

            // 此處等待2s僅類比人臉認證流程
            setTimeout(() => {
              // 建議在接入流程時機3調用getDeviceToken介面
              this.doGetToken();
            }, 2000);
          })
          .margin({ top: 10 })
      }
      .width('100%')
    }
    .height('100%')
  }

  doInit(): void {
    let options: Map<string, string> = new Map<string, string>();
    options.set("IPv6", "0"); //設定IPv4模式
    options.set("DataSwitch", "0"); //設定init階段採集資料
    // options.set("CustomUrl", "xxx"); 設定上報網站Url
    // options.set("CustomHost", "xxx"); 設定上報網站Host
    FaceSecDevice.getInstance().initWithOptions(getContext(), this.USER_PRODUCT_KEY, options, null);
  }

  doGetToken(): void {
    // 傳入bizId樣本，bizId為客戶的業務ID，可以選擇是否傳入。
    let bizId = "1234567890abcdef1234567890ab****"
    let tokenObj: FaceSecToken = FaceSecDevice.getInstance().getDeviceToken(bizId);
    if (tokenObj.code == FaceSecCode.SC_SUCCESS) {
      console.log("Aliyun Token: " + tokenObj.token);
    } else {
      console.log("Aliyun Code: " + tokenObj.code);
    }
  }
}