HarmonyOS

Integration Requirements

• Load and collect the SDK only after the user has agreed to the privacy policy.
• Pass the obtained blackBox directly to your server. Do not cache it on the client.
• It is recommended to complete SDK loading and data collection during app startup, and retrieve blackBox in real time at key business points.

Compliance Notice

Please note that when integrating the SDK product provided by TrustDecision into your app:

1. In accordance with applicable laws and regulations such as the Cybersecurity Law, the Telecommunications Regulations, and the Provisions on the Protection of Personal Information of Telecommunications and Internet Users, as well as regulatory practices, before your end users first launch the app and before you begin collecting information, you should fully inform end users through an interactive interface or design, such as a privacy policy popup, of the purpose, method, and scope of collecting, using, and sharing their personal information with third parties, and obtain their explicit consent.
2. Inform users in text of the following:
   • SDK name: TrustDecision Device Fingerprinting SDK
   • Developer name: Zhejiang Xiaodun Future Technology Co., Ltd.
   • Types of personal information collected: device type, device model, operating system type, device software version, device identifier ODID (optional), GPS location information (optional), Wi-Fi information (including BSSID, SSID, and MAC address, optional), IP address (optional), Wi-Fi status (optional), storage status (optional), screen resolution (optional), battery status (optional), carrier information (optional)
   • Purpose of use: to provide business security and risk control services
   • To ensure your use of the relevant services is compliant, your privacy policy should include authorization for the TrustDecision SDK to provide services and collect, process, and use the relevant information. The above content is for your reference only. The specific wording may be determined by you based on the overall framework and content of your privacy policy.
   • Privacy Policy: https://xiaodun.com/other/privacy/id=4
3. If compliance requirements make it necessary to disable certain collection capabilities, you can disable the corresponding collection items through configuration parameters. If the SDK supports module trimming, you can also exclude the corresponding modules at the dependency stage.

Environment Requirements

Installation and Configuration

Install the SDK

ohpm install @trustdecision/mobrisk

Configure oh-package.json5

Add the third-party package dependency in your project's oh-package.json5:

{
  "dependencies": {
    "@trustdecision/mobrisk": "1.3.1"
  }
}

Declare Permissions

Add the following requestPermissions configuration under the module node in your project's module.json5:

"requestPermissions": [
  {
    "name": "ohos.permission.INTERNET"
  },
  {
    "name": "ohos.permission.GET_NETWORK_INFO"
  },
  {
    "name": "ohos.permission.GET_WIFI_INFO"
  },
  {
    "name": "ohos.permission.STORE_PERSISTENT_DATA"
  },
  {
    "name": "ohos.permission.APPROXIMATELY_LOCATION"
  }
]

Permission Description

Initialization and Collection

Notes

• Call initWithOptions only after the user has agreed to the privacy policy.

Method Definition

public static async initWithOptions(context: Context, params: TDRiskOption): Promise<void>

Example

Execute the following code after the user has agreed to the privacy policy:

import AbilityStage from '@ohos.app.ability.AbilityStage'
import { TDRisk, TDRiskOption } from '@trustdecision/mobrisk'

export default class MyAbilityStage extends AbilityStage {
  async onCreate() {
    const options: TDRiskOption = {
      partnerCode: 'your partnerCode', //please fill in the partnerCode, not the partnerKey
      appKey: 'your appKey',  // Configure AppKey, please contact the operator to obtain
      dataCenter: 'your data center' //Data-center parameters. For the list, please refer to all the configuration instructions below.
    }
    await TDRisk.initWithOptions(this.context, options)
  }
}

Get blackBox

Notes

• Call getBlackBoxAsync / getBlackBox only after initWithOptions has completed.
• Do not cache the returned blackBox in the app. Call the corresponding method each time you need it.
• It is recommended to use the asynchronous method to obtain blackBox for the first time, and then call the synchronous method as needed after the async callback is completed.

Method Definition

/**
 * Asynchronously gets the blackbox.
 * @param priorityCache Whether to return the cached value first. Default is false.
 * false: waits until the current data reporting is completed, then returns the latest blackbox.
 * true: starts data reporting, then returns the cached blackbox first if available for immediate use.
 */
public static async getBlackBoxAsync(priorityCache: boolean = false): Promise<string>
  
/**
 * Synchronously gets the blackbox and directly returns the current available blackbox.
 */
public static getBlackBox(): string

Examples

Asynchronous Retrieval

For the first retrieval and at key business points, it is recommended to use the asynchronous method:

import { TDRisk } from '@trustdecision/mobrisk'

async function getBlackBox() {
  const blackBox = await TDRisk.getBlackBoxAsync();
  console.info('TD_TS', `async blackBox: ${blackBox}`);
}

Synchronous Retrieval

After the first asynchronous retrieval is completed, you can synchronously get it as needed at business points:

import { TDRisk } from '@trustdecision/mobrisk'

function getBlackBox() {
  const blackBox = TDRisk.getBlackBox();
  console.info('TD_TS', `sync blackBox: ${blackBox}`);
}

Best Practices

• Complete SDK loading and collection during app startup after the user has agreed to the privacy policy.
• Retrieve blackBox in real time at key business points such as registration, login, payment, and marketing.
• Rely on synchronous retrieval only after the first asynchronous retrieval has completed.
• Do not reuse historical blackBox values.

Status Check

• When initialization and collection succeed, you can see TD_TS: td sdk init success in the logs.
• When the SDK successfully reports data, the result returned by getBlackBoxAsync() is typically a normal blackBox with a fixed length of 26 characters.
• In exceptional cases, the length of the result returned by getBlackBoxAsync() may increase significantly. For details, refer to Differences Between Normal blackBox and Degraded blackBox

Get SDK Version

const version: string = TDRisk.getSDKVersion()

All Configurations