Integrate the Device Fraud Detection SDK for HarmonyOS

Prerequisites

Before you begin, make sure that you have:

• A development environment that supports HarmonyOS NEXT (0.0.71) or later, with a minimum API version of 12.

• An Alibaba Cloud account and an application created in the Device Fraud Detection console.

The SDK has the following limitations:

• Simulator support — Debugging in simulator mode is not supported.

• Packaging method — Only the bytecode packaging method is supported.

Permissions

To enhance fraud detection accuracy, the SDK requires the following HarmonyOS permissions:

Download and configure the HarmonyOS SDK

1. Download the HarmonyOS SDK and extract the archive. The SDK is provided as a standard HarmonyOS .har package.

2. Copy the .har file to the directory in your project where .har packages are stored. We recommend placing it in the libs directory, following the HarmonyOS official documentation. Then, add the dependency management for the package version in the oh-package.json5 file at the project root.

3. Modify the oh-package.json5 file in your project and add the AliyunDevice dependency to the dependencies section:

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

4. Configure interface obfuscation. To prevent functional errors caused by interface obfuscation, check the obfuscation.txt file within the .har package and do not remove it. If the obfuscation configuration cannot be merged in certain compiler versions, add the obfuscation-rules.txt file from the .har package to your main project and include the obfuscation configuration there.

Initialize the SDK

Call the initialization function as early as possible during app startup. In multi-threaded scenarios, call the initialization API on the main thread and call it only once during the application lifecycle.

export class SecurityInitListener {
  // code indicates the API call status code
  onInitFinish(code: number): void {}
}

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

export class SecurityInitListener {
  // code indicates the API call status code
  onInitFinish(code: number): void {}
}

@State USER_APP_KEY: string = "123e4567e89b12d3a45642661417****";

let options: Map<string, string> = new Map<string, string>();
options.set("IPv6", "0"); // Set to IPv4
// Set a custom data reporting endpoint
// options.set("CustomUrl", "xxx"); Set the reporting site URL
// options.set("CustomHost", "xxx"); Set the reporting site host

SecurityDevice.getInstance().initWithOptions(getContext(),
                            this.USER_APP_KEY, options, null);

Obtain the client token

Obtain the client token and report it to your server. You can then use the server-side device fraud detection API to retrieve device risk information.

export class SecurityToken {
  /**
   * Result code. Refer to SecurityCode for meanings.
   */
  public code:number = 0;

  /**
   * deviceToken returned by the SDK
   */
  public token:string = "";
}

// It is recommended to pass bizId
public getDeviceToken(bizId?: string): SecurityToken

// Example with bizId. bizId is the client's business ID, which is optional.
let bizId = "1234567890abcdef1234567890ab****";
let tokenObj: SecurityToken = SecurityDevice.getInstance().getDeviceToken(bizId);
if (tokenObj.code == SecurityCode.SC_SUCCESS) {
  console.log("Aliyun Token: " + tokenObj.token);
} else {
  console.log("Aliyun Code: " + tokenObj.code);
}

Return codes

Complete code example

The following example shows how to initialize the SDK and obtain a device token.

You can apply for the USER_APP_KEY under Device App Management in the Alibaba Cloud console.

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

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

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

            // Wait 3 seconds before getting the 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);
              }
            }, 3000);
          })
          .margin({ top: 10 })
      }
      .width('100%')
    }
    .height('100%')
  }
}

Call the device fraud detection API

After obtaining the deviceToken, send it to your business server for verification. Refer to the API integration to build requests and call the device fraud detection API.

FAQ

For frequently asked questions about the Device Fraud Detection SDK, see the FAQ.