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 } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig } from '@guancecloud/ft_sdk/src/main/ets/components/Configs';
import { EnvType } from '@guancecloud/ft_sdk/src/main/ets/components/enum/Enums';

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');
        // dbCacheLimit defaults to 100MB, call .setDbCacheLimit(sizeInBytes) to customize
        // rumCacheLimitCount defaults to 100000, call .setRumCacheLimitCount(count) to customize
        // logCacheLimitCount defaults to 5000, call .setLogCacheLimitCount(count) to customize

      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`
`debug`	`boolean`	No	Whether to print Debug logs, default `false`
`env`	`string \\| EnvType`	No	Environment, default `prod`. Can pass `EnvType` enum or string
`serviceName`	`string`	No	Business or service name, default `df_rum_harmonyos`
`autoSync`	`boolean`	No	Whether to automatically sync to server after collection, default `true`
`syncPageSize`	`number`	No	Number of entries per sync request, range `[5,)`, default `10`
`dbCacheLimit`	`number`	No	DB cache limit size, range `[30MB,)`, default `100MB`, unit byte
`rumCacheLimitCount`	`number`	No	RUM data cache count limit, default `100000`, minimum `10000`
`logCacheLimitCount`	`number`	No	Log data cache count limit, default `5000`, minimum `1000`
`dbCacheDiscard`	`string`	No	Data discard rule: `discard` discard new data, `discardOldest` discard old 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 } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';
import { UserData } from '@guancecloud/ft_sdk/src/main/ets/components/rum/bean/UserData';

// 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('[email protected]');
userData.setExts({
  'user_type': 'vip'
});
await FTSDK.bindRumUserData(userData);

await FTSDK.unbindRumUserData();

Runtime Capabilities¶

Manual Data Sync¶

When autoSync is configured as false, manual data sync needs to be triggered:

import { FTSDK } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';

FTSDK.flushSyncData();

Clear SDK Cache Data¶

import { FTSDK } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';

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)