사용자 정의 태그와 글로벌 컨텍스트¶
이 문서에서는 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(...) 완료 후 다음 인터페이스를 통해 동적으로 태그를 추가할 수 있습니다. 설정 후 즉시 적용되며, 이후 전송되는 데이터에 자동으로 해당 태그가 포함됩니다. 이 방식은 로그인, API 요청 또는 로컬 비동기 초기화 완료 후에 태그 값을 얻을 수 있는 시나리오에 적합합니다. 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의 글로벌 변수를 덮어씁니다.