Custom Tags and Global Context¶

This document describes the configuration of custom tags (global context) for the HarmonyOS SDK.

Initialization Configuration¶

Tags determined at application startup can be added via addGlobalContext before SDK configuration is installed.

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

// SDK global context: tags attached to both RUM and Log data.
const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
  .addGlobalContext('app_channel', new String('appgallery'))
FTSDK.install(sdkConfig, context);

// RUM-specific tags.
const rumConfig = new FTRUMConfig()
  .setRumAppId('your-rum-app-id')
  .addGlobalContext('rum_channel', new String('official'));
FTSDK.installRUMConfig(rumConfig);

// Log-specific tags.
const logConfig = new FTLoggerConfig()
  .addGlobalContext('log_source', 'business');
FTSDK.installLogConfig(logConfig);

addGlobalContext on FTSDKConfig and FTRUMConfig adds a single key-value pair at a time. Under ArkTS strict type checking, values can use object wrapper types such as new String(...). FTLoggerConfig.addGlobalContext supports both single key-value pairs and Map/object dictionaries, with values of type string, number, boolean, or an object.

Adding Global Context at Runtime¶

After FTSDK.install(...) completes, tags can be dynamically added via the following APIs; they take effect immediately and are automatically attached to subsequent data uploads. This approach is suitable for scenarios where tag values are obtained only after login, API requests, or local asynchronous initialization completes. Before using RUM- or Log-specific APIs, the corresponding module must be installed.

Note: Dynamic APIs must be called after FTSDK.install(...) completes; calling them before SDK initialization does not persist the tags. Tag keys and values should be non-empty.

appendGlobalContext and appendRUMGlobalContext accept Map<string, string>. appendLogGlobalContext also accepts Record<string, string \| number \| boolean \| object>; Log tag values are converted to strings before upload.

Code Example¶

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

// Dynamically add SDK global tags.
const globalContext = new Map<string, string>();
globalContext.set('login_state', 'logged_in');
FTSDK.appendGlobalContext(globalContext);

// Dynamically add RUM-specific tags.
const rumGlobalContext = new Map<string, string>();
rumGlobalContext.set('page_source', 'push');
FTSDK.appendRUMGlobalContext(rumGlobalContext);

// Dynamically add Log-specific tags; Log supports number, boolean, and object values.
const logGlobalContext = new Map<string, string | number | boolean | object>();
logGlobalContext.set('retry_count', 2);
logGlobalContext.set('is_background', true);
FTSDK.appendLogGlobalContext(logGlobalContext);

Naming Conflict Notes¶

To avoid conflicts between custom fields and SDK data, it is recommended to prefix tag names with a business identifier, for example df_tag_name. When the same key is set repeatedly within the same dynamic scope, the later value overwrites the earlier one.

If a field with the same name exists in the SDK global context and in RUM or Log, the RUM or Log value overrides the SDK global variable.