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/remoteconfig	AE管理画面の設定情報を取得します	>= 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段階で取得が1回自動的にトリガーされます）
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