Cocos2d-x SDK利用ガイド

TIP

アクセスする前に、アクセス前アクセス前準備。

でCocos2d-xGitHub (opens new window)取得できます。

Cocos2d-x SDKはiOS、Androidプラットフォームでの動作をサポートし/a>M

最新バージョン:: v1.2.0v1.2.0

**更新時間は、**2022-01-04

ダウンロードアドレス (opens new window)

一、SDKの初期化

1.1統合SDK

1. ダウンロードCocos2d-x SDK (opens new window)リソースブックをダウンロードします
2. CMakeLists.txt以下の構成を追加

list(APPEND GAME_SOURCE
     Classes/ThinkingAnalytics/Common/TDJSONObject.cpp
     )
list(APPEND GAME_HEADER
     Classes/ThinkingAnalytics/Common/TDJSONObject.h
     Classes/ThinkingAnalytics/Common/ThinkingAnalyticsAPI.h
     )
if(ANDROID)
    list(APPEND GAME_SOURCE
         Classes/ThinkingAnalytics/Android/ThinkingAnalyticsAPI.cpp
         )

MacとWindowsプラットフォームをサポートするには、次の構成を追加します

elseif(WINDOWS)
    list(APPEND GAME_HEADER
         Classes/ThinkingAnalytics/Other/ThinkingSDKObject.h
         )
    list(APPEND GAME_SOURCE
         Classes/ThinkingAnalytics/Other/ThinkingAnalyticsAPI.cpp
         )
elseif(MACOSX)
        list(APPEND GAME_HEADER
            Classes/ThinkingAnalytics/Other/ThinkingSDKObject.h
            )
        list(APPEND GAME_SOURCE
            Classes/ThinkingAnalytics/Other/ThinkingAnalyticsAPI.cpp
            ）

3. Android端末設定の追加

• アプリのproj.androidディレクトリにlibsフォルダを追加し、libsフォルダにthinkingsdk.aarを入れます
• proj.androidのappディレクトリの下のbuild.gradle次の構成を追加します

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}

4. iOS側の設定を追加

• XCodeを使用してiOSプロジェクトを開き、ThinkingAnalyticsの下のiOSフォルダをClasses/ThinkingAnalyticsディレクトリに直接ドラッグします

• Build Setting->Other Linker FlagsのDebugとReleaseをそれぞれ追加する

• Build Phases->Compile SourcesのThinkingAnalytics.mm追加-fobjc-arc

1.2 SDKの初期化

#include "./ThinkingAnalytics/Common/ThinkingAnalyticsAPI.h"
using namespace thinkingdata;
ThinkingAnalyticsAPI::init(TA_APP_ID, TA_SERVER_URL);
//支持初始化多个APPID实例
ThinkingAnalyticsAPI::init(TA_APP_ID_1, TA_SERVER_URL_1);

或者
// 获取 TDConfig 实例
Config config(TA_APP_ID, TA_SERVER_URL);
// 设置运行模式为 Debug 模式
config.setModel(DEBUG);
// 初始化 SDK
ThinkingAnalyticsAPI::init(config);
或者

注:一部のデバイスはデフォルトで平文転送を禁止しているため、HTTPS形式の受信側アドレスを使用することを強くお勧めします。

第二に、ユーザIDを設定する

Cocos2d-x SDKを使用すると、SDKはデフォルトでランダムなUUIDを各ユーザーのゲストIDとして使用します。デフォルトのゲストIDは、ユーザーがゲームを再インストールしたり、デバイスを交換したりすると変更されることに注意してください。

2.1ゲストIDの設定（オプション）

ゲームがユーザーごとに独自のビジターID管理システムを持っている場合、identifyを呼び出してビジターIDを設定できます:

ThinkingAnalyticsAPI::identify("cocos2dx_id");

ゲストIDを取得する必要がある場合は、getDistinctIdを呼び出して取得できます

ThinkingAnalyticsAPI::getDistinctId();

2.2アカウントIDの設定とクリア

ユーザーがログインすると、loginを呼び出してユーザーのアカウントIDを設定し、アカウントIDを設定した後、アカウントIDをユーザーIDとして使用し、設定したアカウントIDはlogoutを呼び出すlogoutまで保持します

// 设置账号 ID
ThinkingAnalyticsAPI::login("cocos2dx_user");

// 清除账号 ID
ThinkingAnalyticsAPI::logout();

注意:この方法では、ユーザー登録、ユーザー登録などのイベントはアップロードされません。

三、アップロード事件

をThinkingAnalyticsAPIを介して::track（）イベントとそのプロパティを報告できます。一般的に、ダースから数百の異なるイベントをアップロードする必要がある場合があります。TAのバックグラウンドを初めて使用する場合は、いくつかの重要なイベントをアップロードすることをお勧めします。

私たちもいくつかの自動収集イベントをサポートしています。

3.1アップロードイベント

前に整理したドキュメントに基づいて、イベントのプロパティと情報を送信する条件を設定することをお勧めします。イベント名はstring型で、文字で始まるだけで、数字、文字、下線「_」を含めることができ、長さは最大50文字で、文字の大文字と小文字には敏感ではない。

TDJSONObject eventProperties;
eventProperties.setString("role", "战士");
eventProperties.setNumber("coin",1);
ThinkingAnalyticsAPI::track("thinkingdata",eventProperties);

• イベントプロパティはTDJSONObject型で、各要素はプロパティを表します。
• イベント属性Keyは属性名で、string型で、文字で始まることを規定し、数字、文字と下線「_」を含み、長さは最大50文字で、文字の大文字と小文字に敏感ではない
• プロパティ値には、文字列、数値クラス、bool、List型の4種類があります。

3.2静的共通属性の設定

プレイヤーのゾーンスーツやチャンネルなどの重要な属性は、イベントごとに設定する必要があります。共通イベントプロパティとは、各イベントに含まれるプロパティのことです。setSuperPropertiesを呼び出して共通イベントプロパティを設定できます。イベントを送信する前に、共通イベントプロパティを設定することをお勧めします。

 TDJSONObject userProperties;
 userProperties.setString("level", "100");
 userProperties.setDateTime("dateTime","2020-01-02 10:52:52.290");
 ThinkingAnalyticsAPI::setSuperProperties(userProperties);

パブリックイベントプロパティはキャッシュに保存され、APPを起動するたびに呼び出す必要はありません。を呼び出し呼び出したパブリックイベントプロパティをアップロードした場合、以前のプロパティが上書きされます。パブリックイベントプロパティとtrack()アップロードしたプロパティのKey場合、イベントのプロパティがパブリックイベントプロパティを上書きします。

を削除する必要がある場合は、unsetSuperProperty()、パブリックイベントプロパティのいずれかをクリアでき。すべてのパブリックイベントプロパティを取得する場合は、getSuperProperties;

// 清除属性名为 CHANNEL 的公共属性
ThinkingAnalyticsAPI::unsetSuperProperty("CHANNEL");

// 清空所有公共属性
ThinkingAnalyticsAPI::clearSuperProperties();

// 获取所有公共属性
ThinkingAnalyticsAPI::getSuperProperties();

3.3動的共通属性の設定

バージョンv1.1.0では、動的共通属性の特性が追加され、共通属性は報告時に当時の値を取得できるようになり、会員等級などの可変共通属性が便利に報告できるようになった。で動的パブリックプロパティ設定すると、SDKはイベントに自動的にプロパティを取得し、トリガーされたイベントに追加します。次の例では、タイムアップのたびにイベントに時間を追加し、イベントがトリガーされるとdynamicPropertiesの戻り値をイベントプロパティに追加します。

// 设置动态公共属性，在事件上报时动态获取事件发生时刻
TDJSONObject dynamicProperties()
{
    TDJSONObject obj;
    obj.setNumber("num",1);
    return obj;
}
ThinkingAnalyticsAPI::setDynamicSuperProperties(dynamicProperties);

3.4記録された事件の長さ

イベントの継続時間を記録する必要がある場合は、timeEvent()タイミングを開始し、タイミングを設定するイベント名を設定します。イベントをアップロードすると、自動的にイベントプロパティに#durationを追加して、記録時間を秒単位で表します。

// 调用 TimeEvent 开启对 TIME_EVENT 事件的计时
ThinkingAnalyticsAPI::timeEvent("TIME_EVENT");

// do some thing...

// 通过 Track 上传 TIME_EVENT 事件时，会在属性中添加 #duration 属性
ThinkingAnalyticsAPI::track("TIME_EVENT");

四、ユーザー属性

TAプラットフォームで現在サポートされているユーザープロパティ設定インターフェイスはuser_set、user_setOnce、user_add、user_unset、user_delete、user_appendです

4.1ユーザーセット

通常のユーザープロパティでは、user_setを呼び出しuser_setすることができます。このインターフェイスを使用してアップロードされたプロパティは元のプロパティ値を上書きし、以前にユーザープロパティが存在しなかった場合は新しいユーザープロパティを作成します。

TDJSONObject userProperties;
userProperties.setString("role", "战士");
userProperties.setNumber("coin",1);
ThinkingAnalyticsAPI::user_set(userProperties);

イベントプロパティと同様に:

• イベントプロパティはTDJSONObject型で、各要素はプロパティを表します。
• イベント属性Keyは属性名で、string型で、文字で始まることを規定し、数字、文字と下線「_」を含み、長さは最大50文字で、文字の大文字と小文字に敏感ではない
• プロパティ値には、文字列、数値クラス、bool、Listタイプの4種類があります。

4.2 user_set Once

アップロードするユーザープロパティが一度設定されている場合はuser_setOnceを呼び出して設定できます。

TDJSONObject userProperties;
userProperties.setString("role", "战士");
userProperties.setNumber("coin",1);
ThinkingAnalyticsAPI::user_setOnce(userProperties);

注: user_setOnce設定のユーザープロパティタイプと制限はuser_setと一致します。

4.3ユーザー_アド

数値型のプロパティをアップロードするときは、user_addを呼び出してを呼び出してアキュムレータ操作を実行できます。プロパティが設定されていない場合は、0を割り当て0から計算します。負の値を呼び出して、減算操作に相当します。

TDJSONObject userProperties;
userProperties.setNumber("coin",1);
ThinkingAnalyticsAPI::user_add(userProperties);

注: user_addのプロパティタイプとKey値の制限はuser_setと一致しますが、Valueでは数値型プロパティのみを報告できます。

4.4 user_unset

ユーザーのプロパティをリセットする必要がある場合は、user_unsetを呼び出して、ユーザーが指定したユーザープロパティの値を空にすることができます。

ThinkingAnalyticsAPI::user_unset("coin");

4.5ユーザー_削除

ユーザーを削除する場合は、user_deleteを呼び出して削除することができます。ユーザーのユーザー属性を照会することはできませんが、ユーザーが生成したイベントを照会することはできます。

ThinkingAnalyticsAPI::user_delete();

4.6ユーザー_append

UserAppendを呼び出すことことでList型のユーザープロパティに要素を追加できます:

TDJSONObject userProperties;
vector<string> listValue;
listValue.push_back("XX");
userProperties.setList("test",listValue);
ThinkingAnalyticsAPI::user_append(userProperties);

V.自動収集イベント

ThinkingAnalytics SDKは、3つのイベントの自動収集を提供します

• ta_app_install:ゲームがインストールされ、インストール後に初めてゲームを開くとイベントが収集され
• ta_app_start:ゲームがフロントに入った時にそのイベントを採取
• ta_app_end:ゲームがバックグラウンドに戻ったときにイベントを収集

enableAutoTrackインターフェイスを呼び出すと、自動取得を有効にできます。

// 开启自动采集
ThinkingAnalyticsAPI::enableAutoTrack();

注:ゲストIDをカスタマイズする必要がある場合は、自動取得機能を有効にする前にIdentifyインターフェイスを呼び出してゲストIDを設定してください

VI。その他の構成オプション

6.1デバイスIDの取得

SDKは初期化が完了すると、デバイスIDを自動的に生成し、ローカルキャッシュに記録します。同じアプリケーション/ゲームに対して、デバイスのデバイスIDは不変であり、getDeviceId()を呼び出してデバイスIDを取得できます

ThinkingAnalyticsAPI::getDeviceId();

// 以设备ID作为访客ID
// ThinkingAnalyticsAPI::identify(ThinkingAnalyticsAPI::getDeviceId());

6.2印刷アップロードデータLog

ThinkingAnalyticsAPI::enableTrackLog(true);

6.3データ報告の一時停止/停止

5. SDK報告の一時停止

ユーザーがテスト環境にいる場合や、ユーザーがテストアカウントにログインしている場合など、SDKのデータ収集と報告を一時的に停止したい場合は、次のインターフェイスを呼び出してSDKの報告を一時的に停止できます。

特定のインスタンス(メインインスタンスとライトインスタンスを含む)からenableTrackingを呼び出し呼び出して、falseSDKの報告を一時停止することができます。このインスタンスに設定された#distinct_id、#account_id、パブリックプロパティなどは保持されます。このインスタンスが収集したが、まだ報告に成功していないデータは引き続き報告しようとします。その後、このインスタンスは新しいデータを収集して報告することはできません。ゲストID、アカウントID、パブリックプロパティなどは設定できませんが、このインスタンスが設定したパブリックプロパティとデバイスID、ゲストID、アカウントIDなどの情報。

インスタンスの停止状態はローカルキャッシュに保存され、enableTracking、enableTracking、true、SDKインスタンスはデータ収集と報告を再開します。ライトインスタンスはキャッシュされないため、APPを開くたびにライトインスタンスの一時停止状態は保持されず、報告を再開します。

// 暂停默认实例的上报，已缓存数据和已经设置的信息不被清除
ThinkingAnalyticsAPI::enableTracking(false);

// 恢复默认实例的上报
ThinkingAnalyticsAPI::enableTracking(true);

6. SDKの報告を停止(optOutTracking)

GDPRが適用される地域で、ユーザーがデータ収集権限を提供しないことを選択した場合、次のインターフェイスを呼び出してSDKを完全にシャットダウンする機能など、SDKの機能を完全に停止する必要がある場合があります。

optOutTrackingはプライマリインスタンスからのみ呼び出すことができ、との最大の違いは、インスタンスのゲストID、アカウントID、パブリックプロパティ、およびレポートされていないデータキューなど、インスタンスのローカルキャッシュを空にすることです。その後、このインスタンスの取得と報告機能をオフにします。

// 停止默认实例的上报, 并清空本地缓存
ThinkingAnalyticsAPI::optOutTracking();

SDK機能をオフにしている間にTAクラスタ内のユーザーデータを削除する場合は、optOutTrackingAndDeleteUserを呼び出すと、SDKインスタンスの機能を停止する前にuser_deleteデータを報告してユーザーデータを削除できます。

// 停止默认实例的上报，并发送 user_del
ThinkingAnalyticsAPI::optOutTrackingAndDeleteUser();

インスタンスの停止状態もローカルキャッシュに保存され、optInTrackingが呼び出されるまで、その後も報告を続けることができますが、この時点では新しいインスタンス

// 重新开启上报
ThinkingAnalyticsAPI::optInTracking();

6.4 SDKの動作モード

SDKは3つのモードで動作します:

• NORMAL:通常モードでは、データはキャッシュに保存され、特定のキャッシュポリシーに従って報告さ
• DEBUG: Debugモード、データを1つずつ報告します。問題が発生すると、ログと例外でユーザーにプロンプトが表示されます
• DEBUG_ONLY:デバッグのみモードは、データだけをチェックし、入庫しない

注: DEBUGモードは統合フェーズのデータチェックのみに使用され、本番モードでは使用しないでください。

Debugモードが本番環境でオンラインにならないように、指定されたデバイスのみがDebugモードをオンにできるようにします。デバッグモードは、クライアントでデバッグモードがオンになっており、デバイスIDがTAバックエンドの「埋め込みポイント管理」ページの「デバッグデータ」プレートに配置されているデバイスのみがオンになります。

デバイスIDは、次の3つの方法で取得できます。

• TAプラットフォームのイベントデータの#device_idプロパティ
• クライアントログ: SDKの初期化が完了すると、デバイスDeviceIdが印刷されます
• インスタンスインターフェイスを介して呼び出す:デバイスIDを取得

6.5キャリブレーション時間

SDKはデフォルトでイベント発生時刻としてネイティブ時刻を使用し、ユーザーが手動でデバイス時刻を変更するとビジネス分析に影響する場合は、サービス側から取得した現在のタイムスタンプを使用してSDKの時刻を校正できます。その後、イベントデータやユーザー属性設定操作など、指定されていない時間の呼び出しはすべて、キャリブレーション後の時間を発生時間として使用します。

// 1585633785954 为当前 unix 时间戳，单位为毫秒，对应北京时间 2020-03-31 13:49:45
ThinkingAnalyticsAPI::calibrateTime(1585633785954);

NTPから時間を取得してSDKを校正する機能も提供しています。ユーザーがアクセスできるNTPサーバーアドレスを渡す必要があります。その後、SDKは着信NTPサービスアドレスから現在の時刻を取得し、SDK時刻をキャリブレーションします。デフォルトのタイムアウト時間(3秒)以内に正しい結果が得られない場合、その後、ローカル時間を使用してデータを報告します。

// 使用苹果公司 NTP 服务对时间进行校准
ThinkingAnalyticsAPI::calibrateTimeWithNtp("time.apple.com");

注意:

• NTPサーバーのアドレスを慎重に選択して、ネットワークの状態が良好な場合、ユーザー機器がすぐにサーバーに到達できるようにする必要があります。
• NTPサービスを使用した時間キャリブレーションには不確実性があります。

七、関連するプリセット属性

7.1プリセット属性の取得

サービス側の埋め込みポイントにアプリ側のプリセット属性が必要な場合、この方法でアプリ側のプリセット属性を取得してサービス側に渡すことができます。

   //获取属性对象
   PresetProperties* presetProperties =  ThinkingAnalyticsAPI::getPresetProperties();

   //生成事件预置属性
   TDJSONObject* properties = presetProperties->toEventPresetProperties();
   /*
   {
	"#carrier": "中国电信",
	"#os": "Android",
	"#device_id": "abb8e87bfb5ce66c",
	"#screen_height": 2264,
	"#bundle_id": "com.sw.thinkingdatademo",
	"#manufacturer": "realme",
	"#device_model": "RMX1991",
	"#screen_width": 1080,
	"#system_language": "zh",
	"#os_version": "10",
	"#network_type": "WIFI",
	"#zone_offset": 8
    }
   */

    //获取某个预置属性
    string bundleId = presetProperties->bundleId;//包名
    string os =  presetProperties->os;//os类型，如Android
    string systemLanguage = presetProperties->systemLanguage;//手机系统语言类型
    int screenWidth = presetProperties->screenWidth;//屏幕宽度
    int screenHeight = presetProperties->screenHeight;//屏幕高度
    string deviceModel = presetProperties->deviceModel;//设备型号
    string deviceId = presetProperties->deviceId;//设备唯一标识
    string carrier = presetProperties->carrier;//手机SIM卡运营商信息，双卡双待时，取主卡的运营商信息
    string manufacture = presetProperties->manufacturer;//手机制造商 如HuaWei
    string networkType = presetProperties->networkType;//网络类型
    string osVersion = presetProperties->osVersion;//系统版本号
    double zoneOffset = presetProperties->zoneOffset;//时区偏移值

IP、国の都市情報はサービス側で解析されて生成され、クライアントはこれらの属性を取得

8、高度な機能

Cocos2d-x SDKは、最初のイベント、更新可能なイベント、書き換え可能なイベントの3つの特別なタイプのイベントの報告をサポートしています。

8.1初の事件

初回イベントとは、あるデバイスや他の次元のIDに対して、一度だけ記録されるイベントです。たとえば、デバイスで最初に発生したイベントを記録したい場合は、最初のイベントでデータを報告できます。

// 示例：上报设备首次事件, 假设事件名为 DEVICE_FIRST
TDJSONObject jsonObject;
jsonObject.setString("role","战士");
TDFirstEvent *firstEvent = new TDFirstEvent("DEVICE_FIRST",jsonObject);
ThinkingAnalyticsAPI::track(firstEvent);

デバイス以外の他のディメンションで初めてかどうかを判断する場合は、初めてのイベントに設定できますファーストチェックIDたとえば、アカウントの最初のイベントを記録する必要があります。アカウントIDを最初のイベントのFIRST_CHECK_IDに設定できます

// 示例：上报用户账号的首次事件, 假设事件名为 USER_FIRST
TDJSONObject jsonObject;
TDFirstEvent *firstEvent = new TDFirstEvent("USER_FIRST",jsonObject);
//firstEvent->setFirstCheckId("YOUR_ACCOUNT_ID");
ThinkingAnalyticsAPI::track(firstEvent);

注意:サービス側で初めてかどうかのチェックが完了するため、初めてのイベントはデフォルトで1時間遅れて入庫する。

8.2更新可能イベント

更新可能なイベントを使用すると、特定のシナリオでイベントデータを変更する必要がある要件を満たすことができます。更新可能なイベントには、イベントを識別するIDを指定し、更新可能なイベントオブジェクトを作成するときに着信する必要があります。TAバックグラウンドは、イベント名とイベントIDに基づいて更新するデータを決定します。

// 示例： 上报可被更新的事件，假设事件名为 UPDATABLE_EVENT

TDJSONObject jsonObject;
jsonObject.setNumber("status", 3);
jsonObject.setNumber("price", 100);
TDUpdatableEvent *updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject,"test_event_id");
// 上报后事件属性 status 为 3, price 为 100
ThinkingAnalyticsAPI::track(updatableEvent);


TDJSONObject jsonObject_new;
jsonObject_new.setNumber("status", 5);
// 上报后事件属性 status 被更新为 5, price 不变
TDUpdatableEvent *updatableEvent = new TDUpdatableEvent("UPDATABLE_EVENT",jsonObject_new,"test_event_id");
ThinkingAnalyticsAPI::track(updatableEvent);

8.3書き換え可能イベント

書き換え可能イベントは更新可能イベントと類似しており、書き換え可能イベントは最新のデータで履歴データを完全にカバーし、効果的には前のデータを削除し、最新のデータを入庫することに相当する。TAバックグラウンドは、イベント名とイベントIDに基づいて更新するデータを決定します。

// 示例： 上报可被重写的事件，假设事件名为 OVERWRITABLE_EVENT
TDJSONObject jsonObject;
jsonObject.setNumber("status", 3);
jsonObject.setNumber("price", 100);
TDOverWritableEvent *overWritableEvent = new TDOverWritableEvent("OVERWRITABLE_EVENT",jsonObject,"test_event_id");
ThinkingAnalyticsAPI::track(overWritableEvent);


TDJSONObject jsonObject_new;
jsonObject_new.setNumber("status", 5);
TDOverWritableEvent overWritableEvent_new =  new TDOverWritableEvent("OVERWRITABLE_EVENT",jsonObject,"test_event_id");
// 上报后事件属性 status 被更新为 5, price 属性被删除
ThinkingAnalyticsAPI::track(overWritableEvent_new);

リリースノート

v1.2.0 2022/01/04

• MacとWindowsのデータ報告をサポート

v 1.1.12021/11/19

• カスタムインスタンス名のサポート
• MacOS、Windowsプラットフォームのコンパイルに対応
• コード最適化
• アップデートAndroid（2.7.3）、iOS SDK（2.7.3）

v1.1.0 2021/08/24

• 最適化初期化API
• 動的共通プロパティのサポート
• マルチインスタンス、ライトインスタンスをサポート
• サポート時間キャリブレーション

v1.0.1 2021/06/28

• プレハブ属性取得のサポート
• Debugモードのサポートを最適化

v1.0.0 2021/04/15

• ゲストIDとユーザーアカウントの設定に対応
• サポートイベントとユーザープロパティの報告
• 起動/シャットダウン/インストールイベントの自動報告をサポート
• 共通プロパティインターフェイスのサポート
• timeEventインターフェイスのサポート