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. 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: the identifier of 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	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 returned result

  None.

Obtain the client token

Obtain the client token and submit it to your own server. Then, obtain the device risk information of the client through the device risk detection events and returned parameters on the server side.

• Function

  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

• Responses

  The value is a SecurityToken class.

  code: the status code of the operation. The parameter indicates whether the operation is successful. For more information about the value range of the code parameter, see the "Status codes" section of this topic.

  token: the token string information that can be used to query the Alibaba Cloud Device Fraud Detection interface for subsequent business.

  Important

  1. Because data reporting may be delayed, make sure that the time interval between the initWithOptions interface and the getDeviceToken interface 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 returned length is about 2 KB.

  3. We recommend that you call the initialization interface in the main thread and only once during the lifecycle of the 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 interface as early as possible when the app starts.

The ALIYUN_APPKEY parameter is used to identify the user identity and can be obtained 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 time interval between the initWithOptions and getDeviceToken interfaces 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 returned 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