CocosCreator

最終更新 2026/10/03

最新バージョン：v1.3.1

更新日：2026-09-16

対応プラットフォーム：Cocos Creator（Web、WeChatミニゲーム、Douyinミニゲーム、Alipayミニゲーム、Android、iOS、HarmonyOS）

リソースのダウンロード： ダウンロード

1. 概要

AE 4.4から、エンゲージモジュールに「構成センター」機能がリリースされました。AE管理画面で機能パラメータの構成を追加し、クライアントSDKでAppに取得することで、プレイヤーとのインタラクション内容をきめ細かくカスタマイズできます。

このドキュメントでは、Cocos CreatorクライアントSDKの統合手順を説明します。ミニゲーム／WebはJSチャンネルを使用し、Android／iOS／HarmonyOSのネイティブパッケージはjsb.reflectionを介してネイティブのTDRemoteConfigを呼び出します。App側はThinkingData SDKとのやり取りだけを考慮すればよく、AE管理画面のタスクの詳細を気にする必要はありません。

先にThinkingData分析SDK（TDAnalytics）を初期化してから、構成センターSDK（TDRemoteConfig）を初期化することをお勧めします。

2. 統合

2.1 SDKの手動統合

構成センターには、次のThinkingData SDKが必要です：

SDK名	説明	バージョン要件
TDAnalytics	データの収集と処理を行います	>= 3.8.0
TDRemoteConfig（JS）	Cocos Creator構成センターSDK	>= 1.3.1

1. tdremoteconfig.mg.cc.min.jsとtdremoteconfig.cc.d.tsをプロジェクトに配置します（例：assets/Script/、assets/libs/）。
2. スクリプトでは通常のモジュールとして読み込みます。Inspectorで「Import As Plugin」にチェックを入れないでください。

import './Script/tdremoteconfig.mg.cc.min.js';

Web／ミニゲームのみをリリースする場合は、JSの統合が完了すれば十分です。Android／iOS／HarmonyOSのネイティブパッケージをリリースする場合は、さらに次の手順に従ってネイティブSDKとブリッジクラスを組み込む必要があります。

2.2 Androidネイティブの追加手順

まずCreatorでAndroidプロジェクトを一度ビルドし、native/engine/androidが生成されてからファイルをコピーします。

1. TDRemoteConfigProxyApi.javaをnative/engine/android/app/src/com/cocos/game/にコピーします。
2. TDRemoteConfig.aarをnative/engine/android/app/libs/にコピーします（プロジェクトにはimplementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])が含まれています）。
3. app/proguard-rules.proに難読化の除外設定を追加します：

-keep public class com.cocos.game.TDRemoteConfigProxyApi { *; }
-keep class cn.thinkingdata.** { *; }
-dontwarn cn.thinkingdata.**

2.3 iOSネイティブの追加手順

まずCreatorでiOSプロジェクトを一度ビルドし、native/engine/iosが生成されてからファイルをコピーします。現在のFrameworkはarm64の実機用パッケージです。

1. TDRemoteConfigProxyApi.h、TDRemoteConfigProxyApi.mm、TDRemoteConfig.frameworkをnative/engine/common/Classes/ThinkingAnalytics/ios/にコピーします。
2. iOSのCMakeにソースファイルを追加し、targetのリンク後にEmbed Frameworksを行います：

list(APPEND CC_COMMON_SOURCES
    "${TE_IOS_DIR}/TDRemoteConfigProxyApi.h"
    "${TE_IOS_DIR}/TDRemoteConfigProxyApi.mm"
)
target_link_libraries(${EXECUTABLE_NAME} "${TE_IOS_DIR}/TDRemoteConfig.framework")
target_link_options(${EXECUTABLE_NAME} PRIVATE "-ObjC")

2.4 HarmonyOSネイティブの追加手順

まずCreatorでHarmonyOSプロジェクトを一度ビルドし、native/engine/harmonyos-nextが生成されてから作業します。以下の手順が1つでも欠けると、jsb.reflectionからブリッジを呼び出せなくなったり、構成のコールバックがJSに戻らなくなったりします。

1. TDRemoteConfigProxyApi.tsをentry/src/main/ets/に、TDRemoteConfig.harをentry/libs/にコピーします。
2. entry/oh-package.json5に依存関係を追加します：

{
  "dependencies": {
    "@thinkingdata/remoteconfig": "file:./libs/TDRemoteConfig.har"
  }
}

3. EntryAbility.etsでアプリケーションコンテキストを設定します：

globalThis.appContext = this.context;

4. entry/build-profile.json5のbuildOptionでarkOptions.runtimeOnlyを設定します。設定しないと、jsb.reflection.callStaticMethodがブリッジクラスを見つけられません：

arkOptions: {
  runtimeOnly: {
    sources: [
      './src/main/ets/TDRemoteConfigProxyApi.ts'
    ],
    packages: [
      '@thinkingdata/remoteconfig'
    ]
  }
}

5. プロジェクトレベルのnative/engine/harmonyos-next/build-profile.json5でuseNormalizedOHMUrl: trueを有効にします（bytecode HARに必須）。
6. Creatorがエクスポートしたentry/src/main/ets/workers/cocos_worker.tsには、デフォルトでevalStringがありません。構成取得のコールバックはメインスレッドからWorkerにpostされるため、分岐を追加する必要があります。追加しないと、更新をリッスンできません：

case "evalString":
  cocos.evalString(msg.param);
  break;

7. ohpm installを実行してから、HarmonyOSを再ビルドします。

3. 初期化

必ず先にTDAnalytics SDKを初期化してから、TDRemoteConfig.initを呼び出してください。構成センターは分析SDKのアカウント情報とデバイス情報に依存します。ネイティブチャンネルでは自動的にTDRemoteConfigProxyApiが使用されるため、JSでJNI／ObjC／ArkTSを別途記述する必要はありません。

import './tdanalytics.mg.cocoscreator.min.js';
import './tdremoteconfig.mg.cc.min.js';

TDAnalytics.init({
  appId: 'YOUR-APP-ID',
  serverUrl: 'https://your-server-url'
});

TDRemoteConfig.init({
  appId: 'YOUR-APP-ID',
  serverUrl: 'https://your-server-url',
  enableLog: true
});

よく使うパラメータ：

パラメータ	説明	備考
appId	プロジェクトのAPP ID	必須。分析SDKと共用
serverUrl	データ受信URL	必須
enableLog	ログを出力	Debugモードとは異なる
debugMode	'debug'を渡すとテストモードが有効になります	ネイティブチャンネルは'debug'のみを認識し、'debugOnly'は認識しません
templateCode	テンプレートコード	任意
customFetchParams	初期化時に渡すカスタム取得パラメータ	任意

4. 使用方法

4.1 データ構造のサンプル

"configId" : {
    "templateId" : [
        {
          "#strategy_id" : "f712dff93afb1e79caefdf094bda4ba2",
          "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はローカルのデフォルト値を取得します。

形式

ローカルのデフォルト値の構造は、次の形式にする必要があります：

{
    "configId": {
        "templateId": [
            {
              "paramater_x" : ""
            }
        ]
    }
}

直接設定

TDRemoteConfig.setDefaultValues({
    "configId": {
        "templateId": [
            {
              "paramater_x": ""
            }
        ]
    }
}, appId);

デフォルト値のクリア

TDRemoteConfig.clearDefaultValues(appId);

4.3 値の取得

構成項目の下で、リリース済みで配信中の特定タイプの戦略内容を取得します：

let array = TDRemoteConfig.getData().get("configId").get("templateId").arrayValue();

オブジェクト／文字列／数値の例：

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

補足：

configId：エンゲージの構成センターで設定した「構成項目ID」。構成項目の詳細は構成項目管理を参照してください

templateId：エンゲージの構成センターで「構成項目」の下に設定した「テンプレートID」。構成テンプレートの詳細は構成テンプレート管理を参照してください

取得ルール

あるkeyの値を取得する手順：

• そのkeyに対応するリモート構成の値を優先して取得します
• リモートでそのkeyが構成されていない場合は、そのkeyのローカルのデフォルト値を探します
• ローカルのデフォルト値にもそのkeyがない場合は、空を返します。

4.4 更新のリッスン

業務で実際に構成を使用する前に、取得成功のリスナーを追加することをお勧めします。ネイティブのAndroid／iOS／HarmonyOSでは、window._configFetchListenerにコールバックされます。

TDRemoteConfig.addConfigFetchListener((status) => {
  // statusは今回の取得結果
});

通知に含まれるパラメータ

ヒント

通知には、デフォルトで今回のリクエストと前回のリクエストの間に一時的に無効化（suspend）、強制オフライン（force_offline）に変更された戦略のステータスが含まれます。業務の要件に応じて利用できます。使用しない場合は無視してかまいません。

次の方法で通知パラメータを取得します：

let map = statusData["strategy_status_map"];

対応するvalueの構造は次のとおりです。構成項目のテンプレートで戦略IDが20241209の戦略のステータスを表しています。

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

5. テスト送信

接続の利用可否と構成戦略の有効性をすばやく検証できるよう、SDKはテストモードの有効化に対応しています。

TDRemoteConfig.init({
  appId: 'YOUR-APP-ID',
  serverUrl: 'https://your-server-url',
  enableLog: true,
  debugMode: 'debug'
});

クライアントでdebugモードを有効にすると、5秒ごとにテスト戦略を取得します。AEのエンゲージモジュールではテンプレートテストまたは戦略テストを作成できます。構成の取得を待っている間は、フロントエンドのページで進捗ノードを確認できます。

操作ドキュメント構成テンプレート管理の、クライアントのテスト送信の部分を参照してください。

クライアントSDKのテスト送信にはテストデバイスが必要です。テストデバイスリストでテストデバイスを選択または追加できます。

enableLogはログのみを制御し、テストモードには入りません。ネイティブチャンネルでは、debugModeが'debug'の場合のみ有効です。