Fraud Detection：裝置風險SDK Harmony接入

前提條件

• 裝置風險SDK需要在Harmony Next （0.0.71）及以上版本的系統運行，API版本最低支援12。

• 不支援模擬器模式調試。

• 僅支援開啟位元組碼打包方案。

• 為協助落實針對您產品整合第三方SDK情況所應履行的隱私合規義務，降低隱私違規風險，進而實現您產品合規營運的營運目標，請您務必確保選用阿里雲文檔中心官網發布的最新版本產品。在使用裝置風險識別前，請您務必仔細瞭解個人資訊處理規定及《風險識別SDK隱私權政策》進行接入。

許可權說明

為增強風險識別的識別效果，當前SDK需要以下許可權：

下載和配置Harmony SDK

1. 下載Harmony SDK，並完成解壓。SDK為Harmony標準的.har包。

2. 將har檔案拷貝到工程中存放har包的目錄。建議參考鴻蒙官方文檔放至libs目錄下，在工程根目錄的oh-package.json5添加認證包的版本依賴樹管理，樣本如下：

   

3. 修改專案工程中的oh-package.json5檔案，在dependencies中添加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。選擇性參數如下。

  欄位名	說明	樣本
  IPv6	是否使用IPv6網域名稱上報裝置資訊。 預設為“0”：使用IPv4網域名稱； “1”：使用IPv6網域名稱。	"1"

  securityInitListener：裝置風險SDK初始化回調介面，可在回調中判斷初始化是否成功。其中，code欄位取值範圍可參考“狀態傳回值”。

• 傳回值

  無。

擷取用戶端Token

擷取用戶端Token，並上報到業務自己的伺服器，後續通過伺服器端裝置風險識別事件及返回參數，從而擷取用戶端裝置風險資訊。

• 函數原型

  export class SecurityToken {
    /**
     * 結果Code, 含義參照SecurityCode
     */
    public code:number = 0;
  
    /**
     * SDK返回的deviceToken
     */
    public token:string = "";
  }
  
  public getDeviceToken(): SecurityToken

• 傳回值

  SecurityToken類型。

  code：返回介面調用狀態代碼，可用於判斷介面調用是否成功。code欄位取值範圍可參考“狀態傳回值”。

  token：返回 Token 字串資訊，商務就緒後續查詢阿里雲裝置風險識別介面。

  重要

  1. 因資料上報可能存在延遲，請確保SDK的資訊採集initWithOptions介面和getDeviceToken介面調用時間間隔2秒以上。

  2. Token字串在網路環境良好的情境下，長度為1K左右；在網路環境較差的情境下，返回的長度在2K左右。

  3. 建議初始化介面在主線程內調用，且應用的生命週期內只需要調用1次。

狀態傳回值

介面混淆配置

為避免介面被混淆而造成功能異常，請查看har包中obfuscation.txt檔案中的配置，請勿移除該檔案。

範例程式碼

初始化裝置風險識別SDK，initWithOptions介面需要在APP啟動儘可能早的時候調用。

其中，參數ALIYUN_APPKEY用於標識使用者身份，可在阿里雲控制台的裝置App管理申請擷取。

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

在業務需要風險識別的情境下（如註冊、活動推廣等）擷取戶端Token並上報到業務的伺服器端。確保initWithOptions和getDeviceToken介面的調用間隔在2秒以上。

let tokenObj: SecurityToken = SecurityDevice.getInstance().getDeviceToken();
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(() => {
              let tokenObj: SecurityToken = SecurityDevice.getInstance().getDeviceToken();
              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介面

請參考以下文檔來構建請求並調用風險識別API介面：

• 裝置風險識別事件及返回參數

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

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

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

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