目录
此内容是否有帮助?

# 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

← Egret白鷺エンジンミニゲームSDK利用ガイド →