본문으로 건너뛰기

HarmonyOS

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

HarmonyOS SDK에는 DevEco Studio 4.0+, HarmonyOS API 10+가 필요하며, ThinkingData Analytics SDK 1.8.1+에 의존합니다(릴리스 패키지에 선언된 의존성은 1.9.0입니다).

최신 버전: v1.0.0

업데이트 시간: 2026-07-22

리소스 다운로드: 다운로드

1. 개요​

AE 4.4 버전부터 운영 모듈에 구성 센터 기능이 출시되었습니다. AE 백엔드에서 기능 파라미터 구성을 추가하고 클라이언트 SDK를 통해 App으로 가져와, 플레이어와의 상호 작용 콘텐츠를 세밀하게 맞춤 설정할 수 있습니다.

이 문서에서는 HarmonyOS 클라이언트 SDK(@thinkingdata/remoteconfig)의 통합 과정을 소개합니다. App 측에서는 ThinkingData SDK와의 상호 작용만 고려하면 되며, AE 백엔드의 구성 세부 사항은 신경 쓸 필요가 없습니다. API와 아키텍처는 Android tdremoteconfig v1.3.0과 일치합니다.

2. 통합​

구성 센터 HarmonyOS SDK에는 다음 ThinkingData SDK가 필요합니다:

SDK 이름기능 소개버전 요구 사항
@thinkingdata/analytics데이터 수집 및 처리>= 1.9.0
@thinkingdata/remoteconfigAE 백엔드의 설정 정보 가져오기>= 1.0.0

2.1 ohpm 설치(권장)​

ohpm install @thinkingdata/remoteconfig
# 또는
ohpm i @thinkingdata/remoteconfig

호스트 모듈의 oh-package.json5에 의존성을 선언한 후 설치를 실행할 수도 있습니다:

{
  "dependencies": {
    "@thinkingdata/remoteconfig": "1.0.0"
  }
}
ohpm install

2.2 로컬 HAR 통합(개발 / 디버깅)​

{
  "dependencies": {
    "@thinkingdata/remoteconfig": "file:../TDRemoteConfig.har",
    "@thinkingdata/analytics": "file:../TDAnalytics.har"
  }
}
//실행
ohpm install

3. 초기화​

반드시 ThinkingData Analytics SDK를 먼저 초기화한 후 RemoteConfig를 초기화해야 합니다.

3.1 간단한 초기화​

import { TDAnalytics } from '@thinkingdata/analytics';
import { TDRemoteConfig } from '@thinkingdata/remoteconfig';

// 먼저 TA SDK를 초기화합니다
await TDAnalytics.init(context, 'YOUR_APP_ID', 'YOUR_SERVER_URL');

// 그다음 RemoteConfig를 초기화합니다
TDRemoteConfig.enableLog(true); // 개발 단계에서는 활성화를 권장합니다
TDRemoteConfig.init(context, 'YOUR_APP_ID', 'YOUR_SERVER_URL');

3.2 TDRemoteConfigSettings로 초기화(권장)​

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

const settings = new TDRemoteConfigSettings();
settings.appId = 'YOUR_APP_ID';
settings.serverUrl = 'YOUR_SERVER_URL';
// settings.templateCode = 'TEMPLATE_CODE'; // 템플릿이 여러 개일 때 지정하며, 기본적으로 비워 둡니다

// 선택: Debug 모드(캐시 제어를 건너뛰므로 테스트 발송이 쉬워집니다)
// settings.mode = TDRemoteConfigMode.DEBUG;

// 선택: 초기화 시 전달하는 커스텀 가져오기 파라미터
settings.customFetchParams = { platform: 'harmonyos' };

// 선택: 커스텀 버킷 ID(A/B 실험용)
settings.customBucketId = { experiment_key: 'bucket_a' };

// 초기화 콜백(init 단계에서 가져오기를 자동으로 한 번 트리거합니다)
settings.setFetchTask({
  onLocalCacheReady: () => {
    // 로컬 캐시가 준비되었으므로 마지막으로 성공한 구성을 안전하게 읽을 수 있습니다
  },
  onSuccess: () => {
    // 이번 네트워크 가져오기 성공
  },
  onFailure: (code: number, error: string) => {
    // 이번 네트워크 가져오기 실패
  }
});

TDRemoteConfig.init(context, settings);

콜백 트리거 순서:

  1. onLocalCacheReady(): 디스크 캐시 로드가 완료되면 즉시 트리거됩니다(캐시가 있을 때만 트리거됨)
  2. 이어서 네트워크 가져오기를 시작합니다. 성공하면 onSuccess(), 실패하면 onFailure()가 호출됩니다

4. 사용​

4.1 데이터 구조 예시​

"configId" : {
    "templateId" : [
        {
         "#strategy_id" : "2024121001",
          "paramater_x" : "1111",
          "#ops_receipt_properties" : {}
        }
    ],
    "#custom_params" : {

    }
}

참고:

  • configId: 운영 백엔드의 구성 센터 모듈에서 생성한 구성 항목 ID로, 비즈니스 모듈 정보를 식별하는 데 사용됩니다. 구성 항목에 대한 설명은 구성 항목을 참고하십시오
  • templateId: 비즈니스에서 구성 항목 아래에 추가한 템플릿 ID로, 구체적인 기능 모듈 정보를 식별하는 데 사용됩니다. 구성 템플릿에 대한 설명은 구성 템플릿을 참고하십시오
  • #strategy_id: 전략의 고유 ID로, 전략 라이프사이클 관리에 사용됩니다. 구성 전략에 대한 설명은 구성 전략을 참고하십시오
  • paramater_x: 구성 템플릿 파라미터로, 기능 모듈에 필요한 구성 파라미터에 해당합니다
  • #ops_receipt_properties: 이벤트 회수 통계에 사용됩니다. 전략 효과를 자동으로 집계해야 하는 경우(아직 미지원) 회수 이벤트에 이 속성을 포함해야 합니다
  • #custom_params: 클라이언트 구성 채널의 커스텀 파라미터로, 클라이언트로 전달할 유저 속성 정보를 정의할 수 있습니다.

4.2 로컬 기본값 설정​

TDRemoteConfig SDK에서 구성 항목의 기본값을 설정할 수 있습니다. AE 서버에 구성 항목이 추가되지 않았거나 로컬에서 원격 값을 가져오지 못한 경우 SDK는 로컬 기본값을 가져옵니다.

직접 설정​

TDRemoteConfig.setDefaultValues({
  welcome_message: 'Hello',
  max_retry: 3,
  feature_enabled: false
} as Record<string, Object>, 'YOUR_APP_ID');

기본값 비우기​

TDRemoteConfig.clearDefaultValues('YOUR_APP_ID');

4.3 값 가져오기 방법​

구성 항목 아래에서 이미 배포되어 활성화된 특정 유형의 전략 콘텐츠를 가져옵니다:

const array = TDRemoteConfig.getData()
  .get('configId')
  .get('templateId')
  .arrayValue();

필드 타입별로 읽을 수도 있습니다:

const data = TDRemoteConfig.getData('YOUR_APP_ID');

const welcome: string = data.get('welcome_message').stringValue();
const maxRetry: number = data.get('max_retry').numberValue();
const enabled: boolean = data.get('feature_enabled').booleanValue();
const uiConfig: Record<string, Object> = data.get('ui_config').objectValue();

참고:

  • configId: 구성 항목 ID입니다. 자세한 내용은 구성 항목을 참고하십시오
  • templateId: 템플릿 ID입니다. 자세한 내용은 구성 템플릿을 참고하십시오

값 가져오기 규칙​

특정 key의 값을 가져오는 과정:

  • 해당 key에 대응하는 원격 구성 값을 우선 가져옵니다
  • 원격에 해당 key가 구성되어 있지 않으면 해당 key의 로컬 기본값을 찾습니다
  • 로컬 기본값에도 해당 key가 없으면 빈 값을 반환합니다(해당 타입의 빈 값을 반환하며 예외를 발생시키지 않음)

4.4 직접 가져오기​

TDRemoteConfig.fetch('YOUR_APP_ID')
  .onSuccess(() => {
    const value = TDRemoteConfig.getData('YOUR_APP_ID').get('key').stringValue();
  })
  .onFailure((code: number, error: string) => {
    // 가져오기 실패
  });

fetch()는 빈도 제어로 보호되므로 짧은 시간 안에 여러 번 호출해도 네트워크 요청이 중복으로 발생하지 않습니다. 강제로 가져오려면 TDRemoteConfigMode.DEBUG 모드로 초기화하십시오.

4.5 업데이트 리스닝​

SDK 초기화 전후 언제든지 구성 가져오기 성공 알림 리스너를 추가할 수 있습니다:

TDRemoteConfig.addConfigFetchListener({
  onFetchSuccess: (statusData: Record<string, Object>) => {
    // 구성 가져오기 성공
  }
});

알림 이름​

onFetchSuccess(구성 가져오기 성공)

알림에 포함되는 파라미터​

팁

알림에는 기본적으로 이번 요청과 지난 요청 사이에 효력 일시 중지(suspend), 강제 비활성화(force_offline)로 변경된 전략 상태가 포함되며, 비즈니스 요구에 따라 사용할 수 있습니다. 사용할 필요가 없으면 무시해도 됩니다.

다음 방법으로 알림 파라미터를 가져옵니다:

const map = statusData['strategy_status_map'] as Record<string, Object>;

해당 value의 구조 예시는 다음과 같으며, 구성 항목 템플릿에서 전략 id가 20241209인 전략의 상태를 나타냅니다:

{
  "configId" : {
    "templateId" : {
      "20241209" : "suspend"
    }
  }
}

4.6 커스텀 가져오기 파라미터와 Client Params​

커스텀 가져오기 파라미터는 모든 가져오기 요청에 추가됩니다:

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

TDRemoteConfig.removeCustomFetchParam('user_level', 'YOUR_APP_ID');

Client Params는 로컬에 영구 저장되며, 가져오기를 할 때마다 함께 전송됩니다:

TDRemoteConfig.addClientParams({ login_count: 5, vip_level: 2 });
TDRemoteConfig.accumulateNum('launch_count', 1);
const all = TDRemoteConfig.getClientParams();
TDRemoteConfig.removeClientParam('vip_level');

4.7 계정 전환​

TA SDK의 login / logout / setDistinctId를 호출하면 원격 구성을 자동으로 다시 가져옵니다(SDK 내부에서 ID 변경을 리스닝함). 앱이 포그라운드로 돌아올 때도 identity 변경을 자동으로 감지합니다.

import { TDAnalytics } from '@thinkingdata/analytics';

TDAnalytics.login('user_account_id');
TDAnalytics.logout();
TDAnalytics.setDistinctId('new_distinct_id');

5. 테스트 발송​

연동의 사용 가능 여부와 구성 전략의 유효성을 빠르게 검증할 수 있도록 SDK는 테스트 모드를 지원합니다.

const settings = new TDRemoteConfigSettings();
settings.mode = TDRemoteConfigMode.DEBUG;
settings.appId = 'YOUR_APP_ID';
settings.serverUrl = 'YOUR_SERVER_URL';
TDRemoteConfig.init(context, settings);

클라이언트에서 Debug 모드를 활성화하면 테스트 전략 주기에 따라 구성을 가져옵니다. AE 운영 모듈에서 템플릿 테스트 또는 전략 테스트를 생성할 수 있으며, 구성 가져오기를 기다리는 동안 프런트엔드 페이지의 진행 노드를 확인할 수 있습니다.

구성 템플릿 문서의 클라이언트 테스트 발송 부분을 참고하십시오.

클라이언트 SDK 테스트 발송에는 테스트 디바이스가 필요합니다. 테스트 디바이스 목록에서 테스트 디바이스를 선택하거나 추가할 수 있습니다.

개발 단계에서는 문제 해결을 위해 SDK 로그를 활성화할 수도 있습니다:

TDRemoteConfig.enableLog(true);
hdc shell hilog -T TDRemoteConfigSDK
이 문서가 도움이 되었나요?
이 페이지의 내용