目录
此内容是否有帮助?

# Unreal Engine SDK 使用ガイド

TIP

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

ThinkingAnalytics は Unreal 4 に組み込まれた Analytics サービスを実装し、C++コード呼び出しインターフェイスを介して直接データを報告することもサポートしています。現在、Android、iOS、 Windows、MacOS プラットフォーム。

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

**更新時期は、**2021-12-3131

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

# I.統合 SDK

# 1.1 統合 ThinkingAnalytics プラグイン

ダウンロードUnreal SDK (opens new window)、解凍後ThinkingAnalyticsプロジェクトの PluginsPluginsディレクトリにPluginsディレクトリが存在しない場合は、まずプロジェクトルートディレクトリ下に Plugins ディレクトリを作成し、ThinkingAnalyticsディレクトリに配置します。

# 1.2 ThinkingAnalytics プラグインのアクティブ化

を有効にするには、次の手順を実行する必要があります

  • Unreal Editor の再起動

  • [編集]>[プラグイン]を開き、[プロジェクトAnalytics]カテゴリで[ThinkingAnalytics]を有効にします

  • を使用する場合は、組み込みAnalyticsカテゴリの下のAnalytics Blueprint Library

  • 再起動 Unreal Editor

  • [編集]>[プロジェクト設定]を開き、[プラグイン]カテゴリで[ThinkingAnalytics]パラメーターを設定します

    • Server Url:必須。受信側のアドレスは、https タイプのアドレスが必要です
    • App ID:必須。プロジェクトの APP ID は、TA バックエンドプロジェクト管理ページで確認できます
    • SDK MODE: SDK 実行モード、デフォルトは通常モード(Normal)で、SDK モードを参照SDK モード
    • Enable Log:クライアントログを開くかどうか
    • TimeZone:オプションで、タイムゾーンを揃える必要がある場合は、"Asia/Shanghai","UTC"などの仕様の TimeZone ID を入力してください時間帯を揃える必要がない場合は記入不要

      注:Windows/MacOS はタイムゾーンの整列を一時的にサポートしていません。

  • のConfigディレクトリのDefaultEテキストに次を追加します。

[Analytics]
ProviderModuleName=ThinkingAnalytics
  • を C++コードで直接使用する場合は、プロジェクトの*.Build.csテキストに以下を追加します。
PrivateDependencyModuleNames.AddRange(new string[] { "ThinkingAnalytics" });

PrivateIncludePathModuleNames.AddRange(new string[] { "ThinkingAnalytics" });

また、SDK を使用するテキストに ThinkingAnalytics. hを引用します。

#include "ThinkingAnalytics.h"

# 1.3 SDK の初期化

を呼び出す前に、まず SDK の初期化インターフェイスを呼び出す必要があります。

ブループリントを使用する場合は、まず Analytics Blueprint LibraryAnalytics Blueprint Libraryのを呼び出す必要があります。でThinking AnalyticsInitialize インターフェイスを呼び出すこともできます。

C++コードで呼び出す場合は、次のように呼び出すことができます

// 初始化 SDK
UThinkingAnalytics::Initialize();

初期化が完了すると、SDK を使用してイベントを報告できます。を使用Analytics Blueprint Libraryの RecordEventインターフェイスインターフェイスを使用して、UE4 の公式Blueprint Analytics プラグイン (opens new window)ガイドを参照して、または以下に説明するUThinkingAnalyticsクラスが提供するインターフェイスを使用してください。

# 第二に、ユーザ ID を設定

デフォルトでは、SDK はランダムな UUID をゲスト ID として使用してユーザーを識別します。

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

ゲームに独自のゲスト ID 管理システムがある場合は、Identify を呼び出してゲスト ID を設定できます

UThinkingAnalytics::Identify("your_distinct_id");

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

FString distinctId = UThinkingAnalytics::GetDistinctId();

# 2.2 アカウント ID の設定

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

// 设置账号 ID
UThinkingAnalytics::Login("your_account_id");

// 清除账号 ID
UThinkingAnalytics::Logout();

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

のAnalytics Blueprint Libraryの SetUserIdインターフェイスインターフェイスは上記のLoginインターフェイスに相当します。

# 三、アップロード事件

のAnalytics Blueprint LibraryからRecordEventインターフェイスから時間を報告するか、Json を使用して C++コードでイベントプロパティを持つイベントをより柔軟に報告できます。一般的に、ダースから数百の異なるイベントをアップロードする必要があります。TA のバックグラウンドを初めて使用する場合は、いくつかの重要なイベントをアップロードすることをお勧めします。

# 3.1 アップロードイベント

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

  • イベントプロパティは、JSON 形式のFString型です
  • イベント属性Keyは属性名で、文字で始まることができ、数字、文字、下線「_」を含むことが規定され、長さは最大 50 文字で、文字の大文字と小文字に敏感ではない
  • プロパティ値は、文字列、数値クラス、bool、JSONArray の 4 種類をサポートします
// 上报一个不带属性事件
UThinkingAnalytics::Track("TEST_EVENT", "");

# 3.2 記録された事件の長さ

を呼び出してTimeEventタイミングを開始し、タイミングを設定するイベント名を設定します。イベントをアップロードすると、自動的にイベントプロパティに#durationを追加して、レコードの長さを秒で表します。

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

// do some thing...

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

注: Windows/MacOS では、イベントの記録時間は一時的にサポートされていません。

# 四、ユーザー属性

TA プラットフォームで現在サポートされているユーザープロパティ設定インターフェイスはUserSet、UserSetOnce、UserAdd、UserDelete、UserUnset、UserAppend.

# 4.1 ユーザーセット

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

// UserSet 接口定义
UThinkingAnalytics::UserSet(const FString& Properties);

ユーザー属性のフォーマット要件は、イベント属性と同様です。

# 4.2 User SetOnce

アップロードするユーザープロパティが一度設定されている場合は、UserSetOnce を呼び出してUserSetOnceすることができます。プロパティに値がある場合は、この情報は無視されます。

// UserSetOnce 接口定义
UThinkingAnalytics::UserSetOnce(const FString& Properties);

注: UserSetOnce によって設定されたユーザープロパティの種類と制限は、UserSet と一致します。

# 4.3 UserAdd

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

// 数值类用户属性减去 100.9
UThinkingAnalytics::UserAdd("USER_PROP_NUM", -100.9);

注: UserAdd のプロパティタイプと Key 値の制限は UserSet と一致しますが、Value では数値タイプのみが許可されます。

# 4.4 ユーザー削除

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

// 删除用户
UThinkingAnalytics::UserDelete();

# 4.5 UserUnset

ユーザーのプロパティをリセットする必要がある場合は、UserUnset、設定済みのプロパティを削除できます。

// 删除某个用户属性
UThinkingAnalytics::UserUnset("userPropertyName");

# 4.6 UserAppend

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

// UserSetOnce 接口定义
UThinkingAnalytics::UserAppend(const FString& Properties);

# V.自動収集イベント

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

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

を呼び出してEnableAutoTrackインターフェイスを呼び出して自動取得を有効にします。

// 开启自动采集
UThinkingAnalytics::EnableAutoTrack();

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

Windows/MacOS では、イベントの自動収集は一時的にサポートされていません。

# 六、その他のインタフェース

# 6.1 デバイス ID の取得

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

FString deviceId = UThinkingAnalytics::GetDeviceId();

# 6.2 フラッシュ

デフォルトでは、データはローカルキャッシュに保存され、特定の報告ポリシーに従ってサービスにアップロードされます。キャッシュ内のデータをすぐに報告する場合は、Flushインターフェイスを呼び出します。Analytics Blueprint LibraryのFlushEventsインターフェイスも最終的に呼び出しFlush:

UThinkingAnalytics::Flush();

# 6.3 キャリブレーション時間

# タイムスタンプ校正

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

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

# NTP キャリブレーション

v1.3.0 に NTP タイムキャリブレーションインターフェイスを追加しました。その後、SDK は着信 NTP サービスアドレスから現在の時刻を取得し、SDK 時刻をキャリブレーションします。デフォルトのタイムアウト時間(3 秒)以内に正しい結果が得られない場合、その後、ローカル時間を使用してデータを報告します。

UThinkingAnalytics::CalibrateTimeWithNtp(const FString& urlString);

注:キャリブレーション時間は、初期化が完了した後、自動取得をオンにしたり、他のデータを報告したりする前に行う必要があります。Windows/MacOS は時間キャリブレーションを一時的にサポートしていません。

# 6.4 データ報告の一時停止/停止

SDK の報告を停止するインターフェイスには、次の 2 種類があります

# SDK の一時停止(EnableTracking)

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

SDK の停止状態はローカルキャッシュに保存され、EnableTracking が呼び出されが渡さtrue、SDK はデータ収集を再開して報告します。

// 暂停上报，已缓存数据和已经设置的信息不被清除
UThinkingAnalytics::EnableTracking(false);

// 恢复上报
UThinkingAnalytics::EnableTracking(true);

# SDK の報告を停止(OptOutTracking)

特定のシナリオでは、SDK の機能を完全に停止する必要がある場合があります。たとえば、GDPR が適用される地域では、ユーザーがデータ収集権限を提供しないことを選択した場合、OptOutTracking を呼び出すことができます.このインターフェイスとのの最大の違いは、ゲスト ID、アカウント ID、報告されていないデータキューなどのローカルキャッシュを空にすることです。その後、収集と報告機能をオフにします。

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

SDK の停止状態も、OptInTracking が呼び出されるまでローカルキャッシュに保存されます。これは、新しいインスタンスに相当します。

// 重新开启上报
UThinkingAnalytics::OptInTracking();

Windows/MacOS は、報告機能の停止/再開を一時的にサポートしていません。

# 6.5 SDK の動作モード

SDK は 3 つのモードで実行できます:

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

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

Windows/MacOs は DEBUG/DEBUG_ONLY/DEBUG_ONLY モードをサポートしていません。

Debug モードが本番環境でオンラインにならないように、指定されたデバイスのみが Debug モードをオンにできるようにします。デバッグモードは、クライアントでデバッグモードがオンになっている場合にのみオンになります。

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

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

# 6.6 パブリックイベントプロパティの設定

v1.3.0 では、ユーザーのメンバーシップレベル、ソースチャネルなどの重要なプロパティをイベントごとに設定する必要があるパブリックイベントプロパティを設定します。共通イベント属性とは、イベントごとに持つ属性のことです。イベントを送信する前に、パブリックイベントプロパティを設定することをお勧めします。

UThinkingAnalytics::SetSuperProperties("{\"static_property1\":\"value1\",\"static_property2\":\"value2\"}");

設定されたパブリックイベントプロパティを取得することもできます。

FString SuperProperties = UThinkingAnalytics::GetSuperProperties();

# 6.7 動的共通属性の設定

v1.3.0 で動的共通プロパティを設定し、動的共通プロパティクラスを設定した後、SDK は自動的に実行し、イベントプロパティを報告したときに戻り値のプロパティを取得し、各イベントに追加します。

// 定义动态公共属性函数
static FString TDReturnDyldParams() {
    return "{\"dyld_property1\":\"value1\",\"dyld_property2\":\"value2\"}";
}

// 设置动态公共属性
void UMyDemoWidget::callSetDynamicSuperPropertiesFunction(){
    UThinkingAnalytics::dynamicPropertiesMap.insert(pair<FString,FString(*)(void)>("inset your appid" ,&TDReturnDyldParams));
}

# 6.8 プレハブ属性の取得

v1.3.0 では、事前取得プロパティインターフェイスが追加され、SDK ではイベントプロパティが報告されたときに、事前設定プロパティを取得できる組み込みプロパティが自動的に追加されます。

FString PresetProperties = UThinkingAnalytics::GetPresetProperties();

# 七、高度な機能

v1.1.0 以降、SDK では、最初のイベント、更新可能なイベント、書き換え可能なイベントの 3 種類のイベントの報告がサポートされています。これらの 3 つのイベントは、TA システム 2.8 以降のバージョンで使用する必要があります。特殊なイベントは特定の場面でしか適用されないので、数値計算技術の顧客成功とアナリストの助けを得て、特殊なイベントを使ってデータを報告してください。

# 7.1 初の事件

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

UThinkingAnalytics::TrackFirst(const FString& EventName, const FString& Properties);

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

UThinkingAnalytics::TrackFirstWithId(const FString& EventName, const FString& Properties, const FString& FirstCheckId);

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

# 7.2 更新可能イベント

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

UThinkingAnalytics::TrackUpdate(const FString& EventName, const FString& Properties, const FString& EventId);

# 7.3 書き換え可能イベント

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

UThinkingAnalytics::TrackOverwrite(const FString& EventName, const FString& Properties, const FString& EventId);

# リリースノート

# v1.4.0 2021/12/31

  • 新しい Windows と MacOS プラットフォームは、イベント、ユーザー属性、高度な機能、共通属性
  • を追加 Windows および MacOS プラットフォームのプリセットプロパティ
  • 部分的なコードロジック調整

# v1.3.0 2021/08/27

  • プレハブ属性取得インタフェースを追加
  • 動的共通プロパティの設定
  • NTP/タイムスタンプ方式の校正時間
  • 静的共通属性の設定と取得

# v1.2.1 2021/06/29

  • ゲスト ID 取得のサポート
  • デバイス ID 取得のサポート

# v1.2.0 2021/06/03

  • 最適化 install, start イベント報告ロジック
  • データ転送フォーマットの最適化
  • 新しいプリセットプロパティ#bundle_id(アプリ固有 ID)
  • コード最適化
  • ネイティブ SDK バージョンのアップグレード

# v1.1.0 2020/08/25

  • 最初のイベントをサポートし、着信カスタム ID が最初に報告されているかどうかをチェック
  • 更新可能で書き換え可能なイベントをサポート
  • #lib/#lib_version フィールドを UE4 SDK 情報
  • ネイティブ SDK バージョンを v2.6.0 にアップグレード

# v1.0.3 2020/06/28

  • コードの最適化: Android 環境での偶発的なヌルポインタ例外

# v1.0.2 2020/06/23

  • 新しいプリセットプロパティ#system_language
  • ネイティブ SDK バージョンのアップグレード

# v1.0.1 2020/05/27

  • 不合理な依存によるパッケージエラーを解決する

# v1.0.0 2020/05/18

  • イベントの報告とすべてのユーザープロパティインターフェイス
  • サポート DEBUG モード
  • タイムゾーンアライメントとタイムキャリブレーション
  • 他のセカンダリインターフェイスのサポート: Flush, OptOutTracking, OptInTracking, EnableTracking