고급 가이드

최근 업데이트 2026. 09. 03.

1. 초기화 파라미터

HarmonyOS의 RemoteConfig는 TDRemoteConfigSettings로 초기화합니다(Analytics SDK의 초기화 설정과는 별개입니다). 자세한 필드는 다음과 같습니다:

1.1 TDRemoteConfigSettings

속성 이름 / 메서드	타입	설명
appId	string	AE 백엔드에서 생성한 프로젝트의 app id(필수)
serverUrl	string	AE 백엔드에서 생성한 프로젝트의 server url(필수)
templateCode	string	템플릿 code. 전달하지 않으면 SDK 내부에서 기본 템플릿 사용
mode	TDRemoteConfigMode	SDK 실행 모드 열거형, 기본값 NORMAL
customFetchParams	Record<string, Object>	초기화 시 전달하는 커스텀 가져오기 파라미터(Fetch 파라미터와 동일)
customBucketId	Record<string, string>	커스텀 버킷 ID(A/B 실험 강제 덮어쓰기용)
setFetchTask(callbacks)	—	init 단계의 가져오기 콜백 등록(onLocalCacheReady / onSuccess / onFailure)

로그 스위치는 Settings에 포함되어 있지 않으므로 다음을 사용하십시오:

TDRemoteConfig.enableLog(true);

예시:

import {
  TDRemoteConfig,
  TDRemoteConfigSettings,
  TDRemoteConfigMode
} from '@thinkingdata/remoteconfig';

const settings = new TDRemoteConfigSettings();
settings.appId = 'YOUR_APP_ID';
settings.serverUrl = 'YOUR_SERVER_URL';
settings.mode = TDRemoteConfigMode.NORMAL;
settings.customFetchParams = { platform: 'harmonyos' };
settings.setFetchTask({
  onLocalCacheReady: () => {},
  onSuccess: () => {},
  onFailure: (code, error) => {}
});
TDRemoteConfig.init(context, settings);

1.2 TDRemoteConfigMode

열거형 값	설명
NORMAL	일반 모드. 캐시 및 만료 정책에 따라 구성을 가져와 로컬에 저장합니다.
DEBUG	Debug 모드. 테스트 발송 / 더 잦은 강제 구성 가져오기에 사용합니다. 디바이스를 AE 콘솔의 테스트 디바이스 목록에 추가해야 하며, 운영 백엔드에서 테스트 진행 노드를 확인할 수 있습니다.

참고: HarmonyOS RemoteConfig는 NORMAL / DEBUG만 제공하며, Analytics 측의 DEBUG_ONLY는 포함하지 않습니다. 수집 관련 Debug 모드는 Analytics SDK에서 별도로 설정하십시오.

2. 가져오기 시점 커스터마이즈

2.1 자동 가져오기

다음과 같은 경우 SDK가 원격 구성 데이터를 자동으로 가져옵니다:

• App 콜드 스타트(TDRemoteConfig.init 후 첫 가져오기 트리거)
• App이 포그라운드/백그라운드로 전환되고 로컬 구성이 만료된 경우(만료 시간은 서버에서 expirationPeriod로 내려주며, 기본값은 12시간)
• ThinkingData Analytics 계정 시스템이 변경된 경우(예: login, logout, setDistinctId)
• 네트워크가 사용할 수 없는 상태에서 다시 사용 가능해지면 누락된 가져오기를 보충
• 타이머 점검: 일반 모드에서는 약 30s마다 만료 여부를 확인하고, Debug 모드에서는 약 5s마다 가져옵니다

2.2 수동 가져오기

SDK 메서드를 수동으로 호출하여 언제든지 원격 구성을 가져옵니다:

TDRemoteConfig.fetch();

체인 콜백 예시:

TDRemoteConfig.fetch()
  .onSuccess(() => {
    // 구성이 업데이트되었습니다
  })
  .onFailure((code: number, error: string) => {
    // 가져오기 실패
  });

이 API에는 내부적으로 빈도 제어 제한이 있으므로 너무 자주 가져오지 마십시오. 더 적극적으로 강제로 가져오려면 TDRemoteConfigMode.DEBUG로 초기화할 수 있습니다.

3. 커스텀 Fetch 파라미터

Fetch 파라미터는 클라이언트 SDK가 AE 서버에 값을 요청할 때 사용할 수 있는 파라미터입니다. Fetch 파라미터를 커스텀하여 구성 채널의 환경 파라미터로 추가하면, 전략을 구성할 때 Fetch 파라미터로 타겟 오디언스 환경을 커스텀할 수 있습니다.

3.1 추가

TDRemoteConfig.setCustomFetchParams({
  user_level: 'vip',
  region: 'cn'
});

초기화 시 Settings로 설정할 수도 있습니다:

settings.customFetchParams = {
  user_level: 'vip',
  region: 'cn'
};

3.2 삭제

지정한 key에 따라 삭제합니다:

TDRemoteConfig.removeCustomFetchParam('user_level');

3.3 커스텀 버킷 ID(선택 사항)

A/B 실험 그룹을 강제로 덮어쓰는 데 사용합니다:

TDRemoteConfig.setCustomBucketId({
  experiment_key: 'bucket_b'
});