Fraud Detection:Device Fraud Detection SDK for HarmonyOS

Prerequisites

• The Device Fraud Detection SDK requires HarmonyOS Next (0.0.71) or later with a minimum API version of 12.

• Debugging on a simulator is not supported.

• Only bytecode packaging is supported.

• To ensure that integration of SDKs meets privacy rules, you must use the latest versions of SDKs that are released on the official website of Alibaba Cloud. This prevents privacy leaks and ensures that your business meets compliance regulations. Before you use Device Fraud Detection, you must understand the regulations on personal information processing and the Privacy Policy of Fraud Detection SDK for integration.

Permissions

To enhance the detection capabilities, the SDK requires the following permissions:

Download and configure HarmonyOS SDK

1. Download the HarmonyOS SDK and extract it. The SDK is a standard HarmonyOS .har package.

2. Copy the .har file to the directory in your project where .har packages are stored. We recommend that you follow the official HarmonyOS documentation and place it in the libs directory. Then, add the version dependency tree management for the authentication package in the oh-package.json5 file in the root directory of your project, as shown in the following example:

   

3. Modify the oh-package.json5 file in your project and add the AliyunDevice dependency package in the dependencies section, as shown in the following example:

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

API operations

The HarmonyOS SDK includes two core API operations: initialization (initWithOptions) and token retrieval (getDeviceToken).

Initialize the SDK

You need to call this function as early as possible when your app starts to complete the internal initialization of the SDK.

• Function syntax

  export class SecurityInitListener {
    // The code parameter specifies the status code of the operation.
    onInitFinish(code: number): void {}
  }
  
  public initWithOptions(ctx: Context, 
                  userAppKey: string, 
                  options: Map<string, string>,
                  securityInitListener: SecurityInitListener): void;

• Parameters

  ctx: the Context of the current Ability.

  userAppKey: identifies the user identity, which can be obtained from the console.

  options: optional initialization parameters. The default value is null. The following table describes the optional parameters.

  Field name	Description	Example
  IPv6	Specifies whether to use IPv6 domain names to report device information. Valid values: 0 (default): IPv4 domain names are used. 1: IPv6 domain names are used.	"1"

  securityInitListener: the listener for the initialization result of Device Fingerprint SDK for Android. You can check whether the initialization is successful based on the callback notification. For more information about the value range of the code parameter, see the "Status codes" section of this topic.

• The response parameters

  None.

Obtain the client token

Obtain the client token and submit it to your application server. Then, you can obtain the device risk information of the client based on the device risk detection events and response parameters from the server.

• Function syntax

  export class SecurityToken {
    /**
     * Result code, refer to SecurityCode for meanings
     */
    public code:number = 0;
  
    /**
     * deviceToken returned by the SDK
     */
    public token:string = "";
  }
  
  public getDeviceToken(): SecurityToken

• The response parameters

  The value is a SecurityToken class.

  code: the status code of the operation. You can check whether the operation is successful based on the status code. For more information about the value range of the code parameter, see the "Status codes" section of this topic.

  token: the token string information, which can be used to query the Alibaba Cloud Device Fraud Detection API.

  Important

  1. Because data reporting may be delayed, make sure that the interval between the initWithOptions and getDeviceToken API operations is more than 2 seconds.

  2. In a good network environment, the token string is about 1 KB in length. In a poor network environment, the token string is about 2 KB in length.

  3. We recommend that you call the initialization operation in the main thread and only once during the lifecycle of your application.

Status codes

Obfuscation configuration

To prevent API operations from being obfuscated and causing functional abnormalities, check the configuration in the obfuscation.txt file in the .har package. Do not remove this file.

Sample code

Initialize the Device Fraud Detection SDK. You need to call the initWithOptions operation as early as possible when your app starts.

The ALIYUN_APPKEY parameter identifies the user identity. You can obtain it from the Device App Management in the Alibaba Cloud Management Console.

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

In business scenarios that require fraud detection, such as account registrations and promotional activities, you must obtain the token of the client and submit the token to the application server. Make sure that the interval between the initWithOptions and getDeviceToken operations is more than 2 seconds.

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);
}

Complete 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) => {
            // Initialize the SDK
            SecurityDevice.getInstance().initWithOptions(getContext(), this.ALIYUN_APPKEY, null, null);

            // Call the operation to obtain the token 2 seconds after initialization.
            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%')
  }
}

Call the Fraud Detection API

Refer to the following documents to build requests and call the Fraud Detection API:

• Device risk detection events and response parameters

• Registration fraud detection features and parameters

• Marketing fraud detection features and parameters

• Login fraud detection features and parameters

• Traffic promotion anti-cheating features and parameters