自定义标签与全局上下文¶
本文介绍 HarmonyOS SDK 自定义标签（全局上下文）的配置方式。
初始化配置¶
应用启动时确定的标签，可在安装配置前通过 addGlobalContext 添加。
import { FTLoggerConfig, FTRUMConfig, FTSDK, FTSDKConfig } from '@guancecloud/ft_sdk/Index';
// SDK 全局标签：会附加到 RUM 和 Log 数据。
const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
.addGlobalContext('app_channel', new String('appgallery'))
FTSDK.install(sdkConfig, context);
// RUM 专属标签。
const rumConfig = new FTRUMConfig()
.setRumAppId('your-rum-app-id')
.addGlobalContext('rum_channel', new String('official'));
FTSDK.installRUMConfig(rumConfig);
// Log 专属标签。
const logConfig = new FTLoggerConfig()
.addGlobalContext('log_source', 'business');
FTSDK.installLogConfig(logConfig);
FTSDKConfig 和 FTRUMConfig 的 addGlobalContext 一次添加一组键值；在 ArkTS 严格类型检查下，值可使用 new String(...) 等对象包装类型。FTLoggerConfig.addGlobalContext 同时支持单组键值和 Map/对象字典，值可为 string、number、boolean 或对象。
运行时添加全局上下文¶
在 FTSDK.install(...) 完成后，可通过以下接口动态添加标签；设置后立即生效，后续上报的数据会自动带上相应标签。该方式适用于登录、接口请求或本地异步初始化完成后才获得标签值的场景。使用 RUM 或 Log 专属接口前，还应完成对应模块的安装。
注意：动态接口必须在
FTSDK.install(...)完成后调用；在 SDK 初始化前调用不会保存标签。标签的 key 和 value 应使用非空值。
| 范围 | 添加接口 | 生效数据 |
|---|---|---|
| SDK 全局 | appendGlobalContext |
RUM 和 Log |
| RUM | appendRUMGlobalContext |
RUM |
| Log | appendLogGlobalContext |
Log |
appendGlobalContext 和 appendRUMGlobalContext 接收 Map<string, string>。appendLogGlobalContext 还支持 Record<string, string \| number \| boolean \| object>；Log 的标签值会转换为字符串后上报。
代码示例¶
import { FTSDK } from '@guancecloud/ft_sdk/Index';
// 动态添加 SDK 全局标签。
const globalContext = new Map<string, string>();
globalContext.set('login_state', 'logged_in');
FTSDK.appendGlobalContext(globalContext);
// 动态添加 RUM 专属标签。
const rumGlobalContext = new Map<string, string>();
rumGlobalContext.set('page_source', 'push');
FTSDK.appendRUMGlobalContext(rumGlobalContext);
// 动态添加 Log 专属标签；Log 支持 number、boolean 和 object 类型的值。
const logGlobalContext = new Map<string, string | number | boolean | object>();
logGlobalContext.set('retry_count', 2);
logGlobalContext.set('is_background', true);
FTSDK.appendLogGlobalContext(logGlobalContext);
命名冲突说明¶
为避免自定义字段与 SDK 数据冲突，建议为标签名称添加业务前缀，例如 df_tag_name。同一动态范围内重复设置相同 key 时，后一次设置会覆盖前一次设置的值。
当 SDK 全局变量与 RUM、Log 中存在同名字段时，RUM、Log 会覆盖 SDK 中的全局变量。