金融级实人认证人脸保镖单独集成HarmonyOS接入_实人认证(ID Verification)-阿里云帮助中心

本文介绍人脸保镖方案的Harmony端接入流程。

使用须知

重要

人脸保镖单独集成方案的应用，依赖业务侧具备成熟的人脸识别算法和风险策略运营体系。建议您可以先和商务经理沟通评估业务场景匹配程度。
为帮助落实针对您产品集成第三方SDK情况所应履行的隐私合规义务，降低隐私违规风险，进而实现您产品合规运营的业务目标，请您务必确保选用阿里云文档中心官网发布的最新版本产品。在使用人脸保镖前，请您务必仔细了解个人信息处理规定及《SDK隐私权政策》。

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 启动的时候，您需要尽可能早地调用该函数。

函数原型

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

调用示例

@State USER_PRODUCT_KEY: string = "<请联系商务经理获取>";

let options: Map<string, string> = new Map<string, string>();
options.set("IPv6", "0");
options.set("DataSwitch", "0");
FaceSecDevice.getInstance().initWithOptions(getContext(), 
                            this.ALIYUN_APPKEY, options, null);

参数说明

ctx：当前 UIContext，或 Context ，可使用 getContext() 方法获取。
userProductKey：用于标识用户身份，阿里云分配的产品 AppKey（不同于AK），请联系商务经理获取。
重要
人脸保镖单独集成方案的应用，依赖业务侧具备成熟的人脸识别算法和风险策略运营体系。建议您可以先和商务经理沟通评估业务场景匹配程度。

options：信息采集可选项，默认可以为null。可选参数如下：

字段名

说明

示例

IPv6

是否使用IPv6域名上报设备信息：

"0"（默认）：否（使用IPv4域名）
"1"：是（使用IPv6域名）

"1"

DataSwitch

是否获取Token时上报设备信息：

"0"（默认）：否（初始化时上报）
"1"：是（获取Token时上报）

说明

建议采用默认配置。

"1"

securityInitListener：初始化回调监听接口，可在回调中判断初始化是否成功，默认可以传入null。
securityInitListener定义
```
public interface FaceSecInitListener {
    // code表示接口调用状态码
    void onInitFinish(int code);
}
```
code 字段取值范围可参考code返回值。

2. 获取客户端Token（getDeviceToken）

获取客户端 token，并上报到业务自己的服务器，后续通过服务器端查询阿里云人脸保镖接口（DescribeFaceGuardRisk），从而获取客户端设备的风险识别信息。

重要

因为数据上报可能存在延迟，请确保 SDK 的 initWithOptions 接口和 getDeviceToken 接口调用时间间隔2秒以上。
调用 getDeviceToken 时建议传入 bizId，可以将本次 token 和业务唯一认证 ID 绑定，后在服务端查询结果时将ID一起传入，可进行防止Token被篡改的校验。
多线程场景下初始化接口需要在主线程调用，且应用的生命周期内只需要调用1次。

// 传入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);
}

参数
bizId：客户的业务ID，可用于关联业务ID和token。默认情况可以不传。

返回值

FaceSecToken 类型，属性如下：

code：返回接口调用状态码，可用于判断接口调用是否成功。

code返回值

FaceSecCode	Code	备注
SC_SUCCESS	10000	SDK信息采集成功
SC_NOT_INIT	10001	SDK未信息采集
SC_NOT_PERMISSION	10002	SDK需要的Harmony基础权限未完全授权
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 字符串信息，可用于业务后续查询阿里云人脸保镖接口。
重要
token 字符串在网络环境良好的场景下，长度为 600 字节左右；在网络环境较差的场景下，返回的长度在 2.5K 左右。
如果业务上出现了大量的长 token，首先请确保客户端的网络是畅通的；其次，请确保 SDK 的 initWithOptions 接口和 getDeviceToken 接口调用间隔在 2 秒以上。

3. 携带Token请求服务端

成功获取deviceToken（FaceSecToken.token）后，可携带此参数请求业务服务器，由服务端查询并校验结果。具体操作，请参见服务端API接口。

完整代码示例

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

@Entry
@Component
struct Index {
  @State message: string = 'Aliyun FaceGuard';
  @State USER_PRODUCT_KEY: string = "<请联系商务经理获取>";

 build() {
    Row() {
      Column() {
        Button(this.message)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .onClick((event: ClickEvent) => {
            // 初始化SDK
            let options: Map<string, string> = new Map<string, string>();
            options.set("IPv6", "0"); //设置IPv4模式
            options.set("DataSwitch", "0"); //设置init阶段采集数据
            FaceSecDevice.getInstance().initWithOptions(getContext(), this.USER_PRODUCT_KEY, options, null);

            // 延时2秒获取Token
            setTimeout(() => {
              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);
              }
            }, 2000);
          })
          .margin({ top: 10 })
      }
      .width('100%')
    }
    .height('100%')
  }
}