Skip to content

SDK Initialization¶

This article covers the initialization and runtime capabilities of the HarmonyOS SDK.

Basic Configuration¶

Initialize the SDK in EntryAbility.ets:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { FTSDK, FTSDKConfig, EnvType } from '@guancecloud/ft_sdk/Index';

const DOMAIN = 0x0000;

export default class EntryAbility extends UIAbility {
  async onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): Promise<void> {
    await this.initFTSDK();
  }

  private async initFTSDK(): Promise<void> {
    try {
      // Local environment deployment (Datakit)
      // const sdkConfig = FTSDKConfig.builder(datakitUrl);

      // Public network DataWay
      const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
        .setDebug(true)
        .setServiceName('Your-App-Name')
        .setEnv(EnvType.PROD);
        // Or use string: .setEnv('prod');
        // ...
        // .enableLimitWithDbSize() To enable DB cache size limit, default is 100MB if dbSize is not provided.

      await FTSDK.install(sdkConfig, this.context);
      hilog.info(DOMAIN, 'FTSDK', 'FT SDK initialized successfully');
    } catch (error) {
      const errorObj: object = error as object;
      hilog.error(DOMAIN, 'FTSDK', `Failed to initialize FT SDK: ${JSON.stringify(errorObj)}`);
    }
  }
}

Field	Type	Required	Description
`datakitUrl`	`string`	Yes	Local environment deployment (Datakit) reporting address, e.g., `http://10.0.0.1:9529`. Choose one between `datakitUrl` and `datawayUrl`.
`datawayUrl`	`string`	Yes	Public network DataWay reporting address, obtained from the [RUM] application. Choose one between `datakitUrl` and `datawayUrl`.
`clientToken`	`string`	Yes	Authentication token, must be configured together with `datawayUrl`.
`setDebug`	`boolean`	No	Whether to print Debug logs, default is `false`.
`setEnv`	`string \\| EnvType`	No	Environment, default is `prod`. Can pass `EnvType` enum or string.
`setServiceName`	`string`	No	Associated business or service name, default is `df_rum_harmonyos`.
`setAutoSync`	`boolean`	No	Whether to automatically sync to the server after collection, default is `true`.
`setSyncPageSize`	`number`	No	Number of entries per sync request, range `[5,)`, default is `10`.
`enableLimitWithDbSize`	`number`	No	Enable DB cache size limit, default is 100MB, unit Byte. When `dbSize` is provided, valid range is `[30MB,)`. After enabling, `FTLoggerConfig.setLogCacheLimitCount` and `FTRUMConfig.setRumCacheLimitCount` will become ineffective.
`setDbCacheDiscard`	`DBCacheDiscard`	No	Set the discard policy when DB cache reaches the size limit, default is `DBCacheDiscard.DISCARD`. `DISCARD` discards appended data, `DISCARD_OLDEST` deletes the oldest cached data.

User Binding and Unbinding¶

Usage¶

/**
 * Bind user information (only user ID)
 * @param id User ID
 */
static bindRumUserDataById(id: string): void

/**
 * Bind user information (complete user data)
 * @param userData User data object
 */
static async bindRumUserData(userData: UserData): Promise<void>

/**
 * Unbind user information
 */
static async unbindRumUserData(): Promise<void>

UserData¶

Method Name	Meaning	Required	Note
`setId`	Set user ID	No
`setName`	Set username	No
`setEmail`	Set email	No
`setExts`	Set user extensions	No	For addition rules, please refer to Custom Tags and Global Context

Code Example¶

import { FTSDK, UserData } from '@guancecloud/ft_sdk/Index';

// Method 1: Bind only user ID (recommended for quick binding)
FTSDK.bindRumUserDataById('user_001');

const userData = new UserData();
userData.setId('user_001');
userData.setName('test.user');
userData.setEmail('test@mail.com');
userData.setExts({
  'user_type': 'vip'
});
await FTSDK.bindRumUserData(userData);

await FTSDK.unbindRumUserData();

Runtime Capabilities¶

Actively Sync Data¶

When autoSync is configured as false, you need to actively trigger data synchronization:

import { FTSDK } from '@guancecloud/ft_sdk/Index';

FTSDK.flushSyncData();

Clear SDK Cached Data¶

import { FTSDK } from '@guancecloud/ft_sdk/Index';

await FTSDK.clearAllData();

clearAllData() will delete all cached data that has not been reported, including:

All data in the sync data table (sync_data_flat)
All data in the RUM view data table (rum_view)
All data in the RUM action data table (rum_action)