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可以增加设备指纹稳定性
ohos.permission.DISTRIBUTED_DATASYNC	否（推荐赋予）	多设备协同。SDK可以检测多设备状态，增强安全效果
ohos.permission.APP_TRACKING_CONSENT	否（推荐赋予）	获取广告标识符权限。SDK获取IDFA信息，增强设备ID稳定性

依赖配置

下载 Harmony SDK（请联系商务经理获取），并解压。SDK 为 Harmony 标准的 .har 包。
将.har文件拷贝到工程中存放har包的目录。建议参考鸿蒙官方文档放至libs目录下，在工程根目录的oh-package.json5添加认证包的版本依赖树管理，并修改版本号，示例如下：
```
{
  ....
  "dependencies": {
    "aliyunfaceguard": "file:./libs/AliyunFaceGuard-xxx.har"
    ....
  }
}
```

接口混淆配置（重要）

为避免接口被混淆而造成功能异常，请查看.har包中obfuscation.txt文件中的配置，请勿移除该文件。

调用SDK

前期准备完成后，可按照下面三个步骤完成客户端接入。

初始化（initWithOptions）
获取客户端Token（getDeviceToken）
携带Token请求服务端

初始化（initWithOptions）

SDK 内部初始化，在 App 启动的时候，您需要尽可能早地调用该函数。

FaceSecDevice.getInstance().initWithOptions(context: UIContext | Context, 
                                            appKey: string, options: Map<string, string>,listener: FaceSecInitListener);

参数说明：

ctx：当前 UIContext，或 Context ，可使用 getContext() 方法获取。
appKey：用于标识用户身份，阿里云分配的AppKey，请联系商务经理获取。
重要
人脸保镖单独集成方案的应用，依赖业务侧具备成熟的人脸识别算法和风险策略运营体系。建议您可以先和商务经理沟通评估业务场景匹配程度。
options：信息采集可选项，默认可以为null。可选参数如下：
字段名
说明
示例
IPv6
是否使用IPv6域名上报设备信息。
0（默认）：使用IPv4域名。
1：使用IPv6域名。
1
listener：初始化回调监听接口，可在回调中判断初始化是否成功，默认可以传入null。
listener定义
```
export class FaceSecInitListener {
  // code表示接口调用状态码
  onInitFinish(code: number): void {}
}
```
code 字段取值范围可参考code返回值。

获取客户端Token（getDeviceToken）

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

重要

因为数据上报可能存在延迟，请确保 SDK 的 initWithOptions 接口和 getDeviceToken 接口调用时间间隔2秒以上。
调用 getDeviceToken 时建议传入 bizId，可以将本次 token 和业务唯一认证 ID 绑定，后在服务端查询结果时将ID一起传入，可进行防止Token被篡改的校验。

// 传入bizID示例，bizID为客户的业务ID，可以选择是否传入。
let bizID = "1234567890abcdef1234567890ab****"
FaceSecDevice.getInstance().getDeviceToken(bizID).then((tokenObj: FaceSecToken) => {
  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需要的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	其他参数错误。

token：返回 token 字符串信息，可用于业务后续查询阿里云人脸保镖接口。
重要
token 字符串在网络环境良好的场景下，长度为 600 字节左右；在网络环境较差的场景下，返回的长度在 2.5K 左右。
如果业务上出现了大量的长 token，首先请确保客户端的网络是畅通的；其次，请确保 SDK 的 initWithOptions 接口和 getDeviceToken 接口调用间隔在 2 秒以上。

携带Token请求服务端

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

完整代码示例

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

@Entry
@Component
struct Index {
  @State message: string = 'Aliyun FaceGuard';
  @State ALIYUN_APPKEY: string = "123e4567e89b12d3a45642661417****";

  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");
            FaceSecDevice.getInstance().initWithOptions(getContext(), this.ALIYUN_APPKEY, options, null);

            // 延时2秒获取Token
            setTimeout(() => {
              // 传入bizID示例，bizID为客户的业务ID，可以选择是否传入。
              let bizID = "1234567890abcdef1234567890ab****"
              FaceSecDevice.getInstance().getDeviceToken(bizID).then((tokenObj: FaceSecToken) => {
                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%')
  }
}