カスタムタグとグローバルコンテキスト¶
このドキュメントでは、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 は、1回の呼び出しでキーと値のペアを1組追加します。ArkTS の厳格な型チェックの下では、値に new String(...) などのオブジェクトラッパー型を使用できます。FTLoggerConfig.addGlobalContext は、1組のキーと値のペアに加えて Map やオブジェクト辞書もサポートしており、値には string、number、boolean、またはオブジェクトを使用できます。
実行時のグローバルコンテキスト追加¶
FTSDK.install(...) 完了後、以下のインターフェースでタグを動的に追加できます。設定後すぐに有効になり、以降に報告されるデータには自動的に該当タグが付与されます。この方法は、ログイン、API リクエスト、またはローカル非同期初期化の完了後にタグ値を取得するようなシナリオに適しています。RUM または Log 専用インターフェースを使用する前に、対応するモジュールのインストールを完了しておく必要があります。
注意：動的インターフェースは
FTSDK.install(...)完了後に呼び出す必要があります。SDK 初期化前に呼び出してもタグは保存されません。タグのキーと値は空でない値を使用してください。
| 範囲 | 追加インターフェース | 適用データ |
|---|---|---|
| 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）を付けることを推奨します。同じ動的範囲内で同じキーを重複して設定した場合、後から設定した値が前の値を上書きします。
SDK グローバル変数と RUM、Log に同名のフィールドが存在する場合、RUM、Log が SDK グローバル変数を上書きします。