SDK Initialization¶

This document describes HarmonyOS SDK initialization and runtime capabilities.

Basic Configuration¶

Initialize the SDK in EntryAbility.ets:

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

const DOMAIN = 0x0000;

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

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

      // Public network DataWay
      const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
        .setDebug(true)
        .setSdkLogLevel(SDKLogLevel.D)
        .setServiceName('Your-App-Name')
        .setEnv(EnvType.PROD) // or use a string: .setEnv('prod')
        .addGlobalContext('app_channel', new String('appgallery'))
        .setAutoSync(true)
        .setSyncPageSize(SyncPageSize.MEDIUM)
        .setDataSyncRetryCount(5)
        .setSyncSleepTime(0)
        .setCompressIntakeRequests(true);

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

For how to use dynamic configuration and runtime updates of the report address, see Dynamic Configuration and Dynamic Address Updates.

File Cache¶

ft-sdk 0.1.17 and later support writing sync cache and RUM aggregation data to the file cache. To ensure a smooth upgrade, the SDK still uses the SQLite cache by default. If you need the file cache, you can explicitly enable it in FTSDKConfig.

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .enableFileDataStore();

To first verify the file cache writes, you can enable shadow writes. When enabled, the SDK still reads and uploads data from SQLite while mirroring writes to FileStore. After validation passes, switch to enableFileDataStore().

const shadowConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setFileDataStoreShadow(true);

Cache Size Limit¶

For ft-sdk 0.1.17 and later, it is recommended to use enableLimitWithCacheSize to configure the SDK total cache size limit. When enabled, the individual log entry count limit FTLoggerConfig.setLogCacheLimitCount and the RUM entry count limit FTRUMConfig.setRumCacheLimitCount no longer take effect.

import { CacheDiscard, FTSDKConfig } from '@guancecloud/ft_sdk/Index';

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  // Enable the total cache size limit. Example: 100MB.
  .enableLimitWithCacheSize(100 * 1024 * 1024)
  // Delete the oldest cached data when the cache reaches the limit.
  .setCacheDiscard(CacheDiscard.DISCARD_OLDEST);

Upload Network Configuration¶

setProxy(...), setProxyAuthenticator(...), and setDns(...) only affect the requests the SDK uses to upload data to DataKit or DataWay. They do not modify the network configuration of application business requests.

import {
  FTSDK,
  FTSDKConfig,
  FTProxyConfig,
  FTProxyAuthenticator,
  FTDnsConfig
} from '@guancecloud/ft_sdk/Index';

const proxyConfig: FTProxyConfig = {
  host: 'proxy.example.com',
  port: 8080,
  exclusionList: ['localhost', '127.0.0.1']
};

const proxyAuthenticator: FTProxyAuthenticator = {
  username: 'proxy-user',
  password: 'proxy-password'
};

const dnsConfig: FTDnsConfig = {
  servers: ['1.1.1.1', '8.8.8.8'],
  overHttpsUrl: 'https://dns.example.com/dns-query'
};

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setProxy(proxyConfig)
  .setProxyAuthenticator(proxyAuthenticator)
  .setDns(dnsConfig);

FTSDK.install(sdkConfig, this.context);

FTProxyConfig¶

FTProxyAuthenticator¶

If authentication information is set in both FTProxyConfig and FTProxyAuthenticator, the configuration in FTProxyAuthenticator takes precedence.

FTDnsConfig¶

Blacklist Filtering¶

ft-sdk 0.1.15 supports DataKit-compatible blacklist filtering, used to filter Logging and RUM data before it is written to the local cache. This capability is enabled by default and can be disabled with setEnableDataFilter(false).

Blacklist rules are divided into local rules and remote rules:

• Local rules are configured with setDataFilters and support two rule categories: logging and rum.
• When data filtering is enabled and a valid report URL exists, the SDK pulls remote logging and rum rules from DataKit or DataWay.
• Local and remote rules both filter new data; data that matches a rule is not written to the local cache.
• Data is first modified by LineDataModifier, and then blacklist filtering is applied based on the modified content.
• Remote rules clean up matched cached data before upload; local rules only filter new data.
• The SDK checks whether the remote rules have expired each time an upload task starts, and pulls them only after they expire.
• When the server-side pull_interval is a numeric value, its unit is nanoseconds; for example, 10000000000 means 10 seconds. A string value "10" also means 10 seconds, and unit formats such as "10s", "2m", and "1h" are also supported. If it is missing or invalid, it is treated as 10 seconds.
• When the server response content is unchanged, the SDK does not parse or apply the same rules again.

Rule expressions must be enclosed in {} and support the in, not in, match, and not match operators. Multiple conditions can be combined with and / or. Field sources include data tags and fields, as well as data-type identifier fields such as source, measurement, and class; the match operator uses regular expressions.

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

const dataFilters: FTDataFilters = new Map<string, Array<string>>();
dataFilters.set('logging', [
  "{ source in ['df_rum_harmonyos_log'] and message match ['.*password.*'] }"
]);
dataFilters.set('rum', [
  "{ source in [resource] and resource_status in ['404', '503'] }"
]);

const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .setEnableDataFilter(true)
  .setDataFilters(dataFilters);

FTSDK.install(sdkConfig, this.context);

FTDataFilters accepts a Map<string, Array<string>> or an object with the same structure. Category names are case-insensitive; categories other than logging and rum are ignored.

// Disable local and remote blacklist filtering, but keep the configured local rules.
sdkConfig.setEnableDataFilter(false);

// Clear the configured local rules. This does not affect server-side remote rules.
sdkConfig.setDataFilters(null);

When switching to a valid report URL at runtime, the SDK clears the remote rules from the old URL and pulls them again from the new URL; local rules are retained.

User Binding and Unbinding¶

Usage¶

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

/**
 * Binds user information (full user data)
 * @param userData User data object
 */
static bindRumUserData(userData: UserData): void

/**
 * Unbinds user information
 */
static unbindRumUserData(): void

UserData¶

Code Example¶

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

// Method 1: bind only the 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'
});
FTSDK.bindRumUserData(userData);

FTSDK.unbindRumUserData();

Runtime Capabilities¶

Set Automatic Data Sync¶

After SDK initialization, you can use FTSDK.setAutoSync(...) to dynamically enable or disable automatic sync of cached data. When disabled, the SDK still writes collected data to the local cache but does not automatically trigger uploads after collection; you can use FTSDK.flushSyncData() to manage data synchronization yourself.

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

// Disable automatic sync
FTSDK.setAutoSync(false);

// Enable automatic sync
FTSDK.setAutoSync(true);

FTSDKConfig.setAutoSync(...) sets the sync state at SDK initialization; FTSDK.setAutoSync(...) dynamically modifies the sync state after SDK initialization.

Manually Sync Data¶

When automatic sync is disabled, you can manually trigger data sync:

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

FTSDK.flushSyncData();

When automatic sync is enabled, the SDK uses a 10-second aggregation window to merge data generated consecutively within a short period before uploading. flushSyncData() does not wait for this aggregation window: it first flushes the currently pending RUM and Log worker queues into the local sync cache as much as possible, then immediately schedules the upload task. If the queue flush fails, it still continues to attempt to trigger the upload.

Clear SDK Cache Data¶

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

await FTSDK.clearAllData();

clearAllData() deletes all unreported cached data, 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)