HarmonyOS接入

1. 初始化（initWithOptions）

SDK 内部初始化，在 App 启动的时候，您需要尽可能早地调用该函数。请参考接入流程，在[时机1]调用初始化 initWithOptions 接口。

• 函数原型

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

• 参数说明

  • ctx：当前 UIContext，或 Context ，可使用 getContext() 方法获取。

  • userProductKey：用于标识用户身份，阿里云分配的产品 AppKey（不同于AK），请联系商务经理获取。

    重要

    设备助手单独集成方案的应用，依赖业务侧具备成熟的人脸识别算法和风险策略运营体系。建议您可以先和商务经理沟通评估业务场景匹配程度。

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

    说明

    指定站点上报，需要设置CustomUrl和CustomHost为国内指定地域，默认情况不需要设置。

    字段名	说明	示例
    IPv6	是否使用IPv6域名上报设备信息： 0（默认）：否（使用IPv4域名） 1：是（使用IPv6域名）	"1"
    DataSwitch	设备信息上报时机。 0（默认）：初始化时 1：获取Token时 说明 建议采用默认配置。	"1"
    CustomUrl	设置数据上报服务器域名。	"https://cloudauth-device.aliyuncs.com"
    CustomHost	设置数据上报服务器host。	"cloudauth-device.aliyuncs.com"

  • securityInitListener：初始化回调监听接口， 可在回调中判断初始化是否成功， 默认可以传入null，code 字段取值范围可参考code返回值。

    securityInitListener定义

    public interface FaceSecInitListener {
        // code表示接口调用状态码
        void onInitFinish(int code);
    }

• 调用示例

  @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]进行调用，并上报到业务自己的服务器，后续通过服务器端查询阿里云设备助手接口（DescribeFaceGuardRisk），从而获取客户端设备风险识别信息。

• 函数原型

  // 推荐传入bizId
  public getDeviceToken(bizId?: string): SecurityToken

• 参数

  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需要的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 秒以上。

    token 字符串在网络环境良好的场景下，长度为 600 字节左右；在网络环境较差的场景下，返回的长度在 2.5K 左右，并且带有特殊标识：

    • 有网："Tkxxxx"

    • 弱网："UFxxxx"

    如果业务上出现了大量的长 token：

    • 首先，请确保客户端的网络是畅通的；

    • 其次，请参考接入流程进行接入，在[时机1]调用初始化 initWithOptions 接口，在[时机2]调用 getDeviceToken 接口；或确保 SDK 的 initWithOptions 接口和 getDeviceToken 接口调用间隔在 2 秒以上。

• 调用示例

  // 传入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接口。