SDK 初始化¶

本文用于承载 HarmonyOS SDK 初始化与运行时能力相关内容。

基础配置¶

在 EntryAbility.ets 中初始化 SDK：

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 {
      // 本地环境部署（Datakit）
      // const sdkConfig = FTSDKConfig.builder(datakitUrl);

      // 公网 DataWay
      const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
        .setDebug(true)
        .setServiceName('Your-App-Name')
        .setEnv(EnvType.PROD);
        // 或使用字符串: .setEnv('prod');
        // ...
        // .enableLimitWithDbSize() 如需开启 DB 缓存大小限制，不传 dbSize 时默认 100MB

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

字段	类型	必须	说明
`datakitUrl`	`string`	是	本地环境部署（Datakit）上报地址，例如 `http://10.0.0.1:9529`。`datakitUrl` 和 `datawayUrl` 二选一
`datawayUrl`	`string`	是	公网 DataWay 上报地址，从[用户访问监测]应用中获取。`datakitUrl` 和 `datawayUrl` 二选一
`clientToken`	`string`	是	认证 token，需要与 `datawayUrl` 同时配置
`setDebug`	`boolean`	否	是否打印 Debug 日志，默认 `false`
`setEnv`	`string \\| EnvType`	否	环境，默认 `prod`。可传 `EnvType` 枚举或字符串
`setServiceName`	`string`	否	所属业务或服务名称，默认 `df_rum_harmonyos`
`setAutoSync`	`boolean`	否	是否在采集后自动同步到服务器，默认 `true`
`setSyncPageSize`	`number`	否	同步请求条目数，范围 `[5,)`，默认 `10`
`enableLimitWithDbSize`	`number`	否	开启DB缓存大小限制，默认 100MB，单位 Byte。传入 dbSize 时取值范围 `[30MB,)`。开启之后 FTLoggerConfig.setLogCacheLimitCount 及 FTRUMConfig.setRumCacheLimitCount 将失效。
`setDbCacheDiscard`	`DBCacheDiscard`	否	设置DB缓存达到大小上限后的丢弃策略，默认为 `DBCacheDiscard.DISCARD`。`DISCARD` 为丢弃追加数据，`DISCARD_OLDEST` 为删除最早缓存数据。

用户绑定与解绑¶

使用方法¶

/**
 * 绑定用户信息（仅用户 ID）
 * @param id 用户 ID
 */
static bindRumUserDataById(id: string): void

/**
 * 绑定用户信息（完整用户数据）
 * @param userData 用户数据对象
 */
static async bindRumUserData(userData: UserData): Promise<void>

/**
 * 解绑用户信息
 */
static async unbindRumUserData(): Promise<void>

UserData¶

方法名	含义	必须	注意
`setId`	设置用户 ID	否
`setName`	设置用户名	否
`setEmail`	设置邮箱	否
`setExts`	设置用户扩展	否	添加规则请查阅自定义标签与全局上下文

代码示例¶

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

// 方式一：仅绑定用户 ID（推荐用于快速绑定）
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();

运行时能力¶

主动同步数据¶

当配置 autoSync 为 false 时，需要主动触发数据同步：

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

FTSDK.flushSyncData();

清理 SDK 缓存数据¶

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

await FTSDK.clearAllData();

clearAllData() 会删除所有未上报的缓存数据，包括：

同步数据表（sync_data_flat）中的所有数据
RUM 视图数据表（rum_view）中的所有数据
RUM 动作数据表（rum_action）中的所有数据