前提條件

• 設備風險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接口進行識別：

設備風險識別事件及返回參數

注冊風險識別功能及參數說明

營銷風險識別功能及參數說明

登錄風險識別功能及參數說明

流量推廣反作弊功能及參數說明