SDK 初始化¶

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

基础配置¶

在 EntryAbility.ets 中初始化 SDK：

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

      // 公网 DataWay
      const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
        .setDebug(true)
        .setServiceName('Your-App-Name')
        .setEnv(EnvType.PROD);
        // 或使用字符串: .setEnv('prod');
        // dbCacheLimit 默认值为 100MB，如需自定义可调用 .setDbCacheLimit(sizeInBytes)
        // rumCacheLimitCount 默认值为 100000，如需自定义可调用 .setRumCacheLimitCount(count)
        // logCacheLimitCount 默认值为 5000，如需自定义可调用 .setLogCacheLimitCount(count)

      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` 同时配置
`debug`	`boolean`	否	是否打印 Debug 日志，默认 `false`
`env`	`string \\| EnvType`	否	环境，默认 `prod`。可传 `EnvType` 枚举或字符串
`serviceName`	`string`	否	所属业务或服务名称，默认 `df_rum_harmonyos`
`autoSync`	`boolean`	否	是否在采集后自动同步到服务器，默认 `true`
`syncPageSize`	`number`	否	同步请求条目数，范围 `[5,)`，默认 `10`
`dbCacheLimit`	`number`	否	DB 缓存限制大小，范围 `[30MB,)`，默认 `100MB`，单位 byte
`rumCacheLimitCount`	`number`	否	RUM 数据缓存数量限制，默认 `100000`，最小值 `10000`
`logCacheLimitCount`	`number`	否	日志数据缓存数量限制，默认 `5000`，最小值 `1000`
`dbCacheDiscard`	`string`	否	数据丢弃规则：`discard` 丢弃新数据，`discardOldest` 丢弃旧数据

用户绑定与解绑¶

使用方法¶

/**
 * 绑定用户信息（仅用户 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 } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';
import { UserData } from '@guancecloud/ft_sdk/src/main/ets/components/rum/bean/UserData';

// 方式一：仅绑定用户 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/src/main/ets/components/FTSDK';

FTSDK.flushSyncData();

清理 SDK 缓存数据¶

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

await FTSDK.clearAllData();

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

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