menu
Is this helpful?

# Unreal

TIP

実装する前にデータアクセスの準備を確認しておいてください。

TDAnalytics はUnreal のビルトイン Analytics サービスを実装し、C++ コード呼び出しインターフェイスを介して直接データを送信することも対応します。現在、Android、iOS、Windows、および MacOS プラットフォームを対応しています。

最新バージョン: v2.0.1 (opens new window)

更新時間: 2023-11-24

リソースソースコード (opens new window)ダウンロード (opens new window)

# SDK実装

# 1.1 TDAnalytics プラグイン実装

Unreal SDKをダウンロードして解凍し、TDAnalytics をプロジェクトの Plugins ディレクトリに配置します。Plugins ディレクトリが存在しない場合は、まずプロジェクトのルート ディレクトリの下に Plugins ディレクトリを作成してから、TDAnalytics ディレクトリをそこに配置します。

# 1.2 TDAnalytics プラグインを有効

TDAnalytics プラグインを有効にするには、次の手順を実行する必要があります:

  • Unreal Editorを再起動
  • Edit > Plugins, Analyticsカテゴリの元で、 TDAnalyticsを有効
  • Blueprintを使用する場合は、ビルトイン Analytics カテゴリでAnalytics Blueprint Libraryを有効
  • Unreal Editorを再起動
  • Edit > Project、プラグインカテゴリでTDAnalyticsのパラメータ設定:
    • Server Url: 必須。受信アドレスでhttps タイプのアドレスを使用する必要があります
    • App ID: 必須。プロジェクトの APP ID は、TE バックグラウンド プロジェクト管理ページで確認できます。
    • TimeZone: 任意。タイムゾーンを利用する場合は「Asia/Shanghai」「UTC」など標準のタイムゾーンIDを入力してください。タイムゾーンを合わせる必要がない場合は入力不要です
    • Enable Encrypt: データ暗号化を有効にするかどうか。デフォルトは false です。有効にした後、データは暗号化されてTEにアップロードされます。
    • EncryptPublicKey: 任意。未入力の場合、公開鍵の暗号化にデフォルト設定が使用されます
    • EncryptVersion: 任意。入力されていない場合は、デフォルトの構成とキー バージョンが使用されます
    • SymmetricEncryption: 任意。入力されていない場合は、デフォルトの構成、対称キーが使用されます
    • AsymmetricEncryption: 任意。入力されていない場合は、デフォルトの構成、非対称キーが使用されます

注意:Windows/MacOS はタイム ゾーンの調整を対応していません

  • Config ディレクトリの DefaultEngine.ini ファイルに次を追加します。
[Analytics]
ProviderModuleName=TDAnalytics
  • TDAnalytics インターフェイスを C++ コードで直接使用する場合は、プロジェクトの *.Build.cs ファイルに次を追加する必要があります。
PrivateDependencyModuleNames.AddRange(new string[] { "TDAnalytics" });
PrivateIncludePathModuleNames.AddRange(new string[] { "TDAnalytics" });

また、SDK を使用するファイルで TDAnalytics.h ヘッダー ファイルを参照します。

#include "TDAnalytics.h"

# 初期設定

以下はSDK初期設定のコード例:

UTDAnalytics::Initialize();

初期設定が完了したら、SDK を使用してイベントを送信できます。

# メイン機能

メイン機能を利用する前に、ユーザー識別ルールを確認してくだ;

SDKはゲストIDを自動で作成し、ローカルで保存される;ユーザーがログインする前に、ゲストIDを身分識別IDとして使われます。

注意:ゲストIDはユーザーがアプリを再インストール時にリセットされます。

# 3.1 アカウントIDを設置

ユーザーがログインする時に、loginを呼び出して、ユーザーのアカウントIDを設定できます。TEプラットフォームはアカウントIDを身分識別IDとしてlogoutを呼び出しする前までに保留します。loginを数回呼び出すと、前のアカウントIDが上書きされます。

// The login unique identifier of the user, corresponding to the #account_id in data tracking. #Account_id now is TE
UTDAnalytics::Login("TE");

この方法ではログインイベントを送信されません

# 3.2 共通イベントプロパティ設定

共通イベントプロパティは全てのイベントに含まれるプロパティとなります。setSuperPropertiesを呼び出しして設定することできます。イベント送信する前に、共通イベントプロパティを設定しておいてください。

例えば:プレイヤーのレベル、戦闘力、所持資源などのプロパティ

  TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
    Properties->SetStringField("channel", "TE");//string
    Properties->SetNumberField("age", 1);//number
    Properties->SetBoolField("isSuccess", true);//boolean
    FDateTime DateTime = FDateTime::Now();
    Properties->SetStringField("birthday", FDateTime::FromUnixTimestamp(DateTime.ToUnixTimestamp()).ToString(TEXT("%Y-%m-%d %H:%M:%S.")) += *FString::Printf(TEXT("%03d"), DateTime.GetMillisecond()));//time

    TSharedPtr<FJsonObject> ItemProperties = MakeShareable(new FJsonObject);
    ItemProperties->SetStringField("itemChannel", "item");
    Properties->SetObjectField("object", ItemProperties);//object

    TArray< TSharedPtr<FJsonValue> > DataObjectArray;
    TSharedPtr<FJsonObject> ArrayItemProperties = MakeShareable(new FJsonObject);
    ArrayItemProperties->SetStringField("arrayItemChannel", "array_item");
    TSharedPtr<FJsonValueObject> DataObjectValue = MakeShareable(new FJsonValueObject(ArrayItemProperties));
    DataObjectArray.Add(DataObjectValue);
    Properties->SetArrayField("object_arr", DataObjectArray);//array object

    TArray< TSharedPtr<FJsonValue> > DataArray;
    TSharedPtr<FJsonValueString> DataValue = MakeShareable(new FJsonValueString("data_value"));
    DataArray.Add(DataValue);
    Properties->SetArrayField("arr", DataArray);//array 

    UTDAnalytics::SetSuperProperties(Properties, AppID);
  • Key は当プロパティの名称でstringタイプで、英文字と数字、 "_"を含め、最大50文字。TEシステムは一律で小英文字に統一されます
  • Value は当プロパティの値で、String, Number, Bloon, Time, object, array, list objectを対応しております。

イベントプロパティ、ユーザープロパティは共通イベントプロパティと一致する必要があります。

# 3.3 自動収集イベントのOn/Off

クライアント SDKは一部イベントを自動収集することが可能で、実際業務状況に応じてon/offにしてください。以下は参考となります。

UTDAnalytics::EnableAutoTrack();

# 3.4 イベント送信

trackを呼び出してイベントの送信を行います。事前にデータプランをご用意の上、送信してください。以下はモデルコードとなります。例:アイテム購入

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("product_name", "product name");
UTDAnalytics::Track("product_buy", Properties);

イベント名はstringタイプで、英文字と数字、 "_"を含め、最大50文字まで入力可能です。

# 3.5 ユーザープロパティ設定

一般のユーザープロパティに関しては、UserSetを利用して設定することができますが、 UserSetは元の値を上書きされます。本来該当プロパティに値がない場合は、プロパティが新規作成されます。以下はコード例となります。

 //the username now is TA
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("username", "TA");
UTDAnalytics::UserSet(Properties);
//the username now is TE
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetStringField("username", "TE");
UTDAnalytics::UserSet(NewProperties);

# コード例のまとめ

以下のコード例で全ての操作が含まれます、以下の順で利用推奨しております:

#include "TDAnalytics.h"
if (privacy policy is authorized) {
   
   UTDAnalytics::Initialize();
   
   //if the user has logged in, the account ID of the user could be set as the unique identifier 
   UTDAnalytics::Login("TE");
   
    //After setting Super Properties, each event would have Super Properties
   TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
   Properties->SetStringField("channel", "TE");//string
   Properties->SetNumberField("age", 1);//number
   Properties->SetBoolField("isSuccess", true);//boolean
   FDateTime DateTime = FDateTime::Now();
   Properties->SetStringField("birthday", FDateTime::FromUnixTimestamp(DateTime.ToUnixTimestamp()).ToString(TEXT("%Y-%m-%d %H:%M:%S.")) += *FString::Printf(TEXT("%03d"), DateTime.GetMillisecond()));//time

   TSharedPtr<FJsonObject> ItemProperties = MakeShareable(new FJsonObject);
   ItemProperties->SetStringField("itemChannel", "item");
   Properties->SetObjectField("object", ItemProperties);//object

   TArray< TSharedPtr<FJsonValue> > DataObjectArray;
   TSharedPtr<FJsonObject> ArrayItemProperties = MakeShareable(new FJsonObject);
   ArrayItemProperties->SetStringField("arrayItemChannel", "array_item");
   TSharedPtr<FJsonValueObject> DataObjectValue = MakeShareable(new FJsonValueObject(ArrayItemProperties));
   DataObjectArray.Add(DataObjectValue);
   Properties->SetArrayField("object_arr", DataObjectArray);//array object

   TArray< TSharedPtr<FJsonValue> > DataArray;
   TSharedPtr<FJsonValueString> DataValue = MakeShareable(new FJsonValueString("data_value"));
   DataArray.Add(DataValue);
   Properties->SetArrayField("arr", DataArray);//array
   UTDAnalytics::SetSuperProperties(Properties, AppID);
   //Enable auto-tracking
   UTDAnalytics::EnableAutoTrack();
   //upload events
   TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
   Properties->SetStringField("product_name", "product name");
   UTDAnalytics::Track("product_buy", Properties);
   //Set user properties
   TSharedPtr<FJsonObject> UserProperties = MakeShareable(new FJsonObject);
   UserProperties->SetStringField("username", "TE");
   UTDAnalytics::UserSet(Proper);
}