设备风险SDK Harmony接入

前提条件

• 设备风险SDK需要在Harmony Next （0.0.71）及以上版本的系统运行，API版本最低支持12

• 不支持模拟器模式调试

• 仅支持开启字节码打包方案

权限说明

为增强风险识别的识别效果，当前 SDK 需要以下权限：

下载和配置SDK

1. 下载 Harmony SDK，并完成解压。SDK 为 Harmony 标准的 .har 包。

2. 将har文件拷贝到工程中存放har包的目录。建议参考鸿蒙官方文档放至libs目录下，在工程根目录的oh-package.json5添加认证包的版本依赖树管理，示例如下：

3. 修改项目工程中的oh-package.json5文件，在denpendencies中添加AliyunDevice依赖包，示例如下：

{
  ....
  "dependencies": {
    "aliyundevice" : "file:../libs/HarmonyOS-AliyunDevice-xxx.har"
    ....
  }
}

接口说明

Harmony SDK包含初始化（initWithOptions）、获取Token（getDeviceToken）2 个核心接口。

初始化SDK

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

• 函数原型

export class SecurityInitListener {
  // code表示接口调用状态码
  onInitFinish(code: number): void {}
}

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

• 参数

ctx：当前 Ability 的 Context。

userAppKey：用于标识用户身份， 控制台进行获取。

options：初始化可选项，默认可以为null。可选参数如下

securityInitListener：设备风险SDK初始化回调接口，可在回调中判断初始化是否成功。其中，code字段取值范围可参考“状态返回值”。

• 返回值

无。

获取客户端Token

获取客户端 Token，并上报到业务自己的服务器，后续通过服务器端设备风险识别事件及返回参数，从而获取客户端设备风险信息。

• 函数原型

export class SecurityToken {
  /**
   * 结果Code, 含义参照SecurityCode
   */
  public code:number = 0;

  /**
   * SDK返回的deviceToken
   */
  public session:string = "";
}

public async getDeviceToken(): Promise<SecurityToken>

• 返回值

SecurityToken 类型。

code：返回接口调用状态码，可用于判断接口调用是否成功。code 字段取值范围可参考“状态返回值”。

token：返回 Token 字符串信息，可用于业务后续查询阿里云设备风险识别接口。

注意（非常重要）：

1.因数据上报可能存在延迟，请确保SDK的信息采集initWithOptions接口和getDeviceToken接口调用时间间隔2秒以上。

2.Token 字符串在网络环境良好的场景下，长度为 1K 左右；在网络环境较差的场景下，返回的长度在 2K 左右。

状态返回值

接口混淆配置

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

示例代码

初始化设备风险识别 SDK，initWithOptions 接口需要在 APP 启动尽可能早的时候调用。

其中，参数ALIYUN_APPKEY用于标识用户身份，可在阿里云控制台的设备App管理申请获取。

SecurityDevice.getInstance().initWithOptions(getContext(), 
                             this.ALIYUN_APPKEY, null, null);

在业务需要风险识别的场景下（如注册、活动推广等）获取户端 Token 并上报到业务的服务器端。确保 initWithOptions 和 getDeviceToken 接口的调用间隔在2秒以上。

SecurityDevice.getInstance().getDeviceToken().then((tokenObj: SecurityToken) => {
  if (tokenObj.code == SecurityCode.SC_SUCCESS) {
    console.log("Aliyun Token: " + tokenObj.token);
  } else {
    console.log("Aliyun Code: " + tokenObj.code);
  }
})

完整代码：

import { SecurityCode, SecurityToken, SecurityDevice } from 'aliyundevice';

@Entry
@Component
struct Index {
  @State message: string = 'Aliyun Device';
  @State ALIYUN_APPKEY: string = "XXX";

  build() {
    Row() {
      Column() {
        Button(this.message)
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .onClick((event: ClickEvent) => {
            // 初始化SDK
            SecurityDevice.getInstance().initWithOptions(getContext(), this.ALIYUN_APPKEY, null, null);

            // 延时2秒获取Token
            setTimeout(() => {
              SecurityDevice.getInstance().getDeviceToken().then((tokenObj: SecurityToken) => {
                if (tokenObj.code == SecurityCode.SC_SUCCESS) {
                  console.log("Aliyun Token: " + tokenObj.token);
                } else {
                  console.log("Aliyun Code: " + tokenObj.code);
                }
              })
            }, 2000);
          })
          .margin({ top: 10 })
      }
      .width('100%')
    }
    .height('100%')
  }
}

调用风险识别API接口

将deviceToken与其他参数，根据如下相应的风险识别服务事件参数文档说明，请求风险识别API接口进行识别：

设备风险识别事件及返回参数

注册风险识别功能及参数说明

营销风险识别功能及参数说明

登录风险识别功能及参数说明

流量推广反作弊功能及参数说明