Unreal

Last updated 10/03/2026

tip

Before you integrate the SDK, read Pre-integration preparation.

TDAnalytics implements the built-in Analytics service of Unreal Engine, and also supports reporting data by calling APIs directly from C++ code. It currently supports Android, iOS, Windows, and macOS, and works with Unreal Engine 4.26+ and 5.+.

Latest version: v3.0.3

Update time: 2025-10-11

Downloads: Source code, SDK download

Note

This document applies to v2.0.0 and later. For earlier versions, see Unreal Integration Guide (V1) and SDK download (v1.6.0)

1. Integrate the SDK

1.1 Integrate the TDAnalytics plugin

Download the Unreal SDK, unzip it, and put TDAnalytics into your project's Plugins directory. If the Plugins directory doesn't exist, first create a Plugins directory under the project root, and then put the TDAnalytics directory into it.

1.2 Activate the TDAnalytics plugin

To enable the TDAnalytics plugin, take the following steps:

Restart Unreal Editor
Open Edit > Plugins, and enable TDAnalytics under the project Analytics category
If you use Blueprint, enable Analytics Blueprint Library under the built-in Analytics category
Restart Unreal Editor again
Open Edit > Project Settings, and set the TDAnalytics parameters under the Plugins category:
- Server Url: Required. The receiver URL, which must be an HTTPS URL
- App ID: Required. The APP ID of your project, which you can find on the Project Settings page in the AE backend
- TimeZone: Optional. To align the time zone, enter a standard TimeZone ID, such as "UTC01:00". If you don't need to align the time zone, leave it empty
- Enable Encrypt: Whether to enable data encryption. Defaults to false. When enabled, data is encrypted before it is uploaded to AE
- EncryptPublicKey: Optional. If left empty, the default configuration is used. The public key for encryption
- EncryptVersion: Optional. If left empty, the default configuration is used. The key version
- SymmetricEncryption: Optional. If left empty, the default configuration is used. The symmetric key
- AsymmetricEncryption: Optional. If left empty, the default configuration is used. The asymmetric key

Note: Time zone alignment isn't supported on Windows/MacOS yet.

Add the following to the DefaultEngine.ini file in the Config directory:

[Analytics]
ProviderModuleName=TDAnalytics

To use the TDAnalytics APIs directly in C++ code, add the following to your project's *.Build.cs file:

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

Also, include the TDAnalytics.h header file in the files where you want to use the SDK:

#include "TDAnalytics.h"

2. Initialization

The following sample code initializes the SDK:

// Initialize the SDK
UTDAnalytics::Initialize();

After initialization is complete, you can use the SDK to report events.

3. Common features

Before you use the common features, we recommend that you read the user identification rules. By default, the SDK generates a random number as the distinct ID and stores it locally. Before a user logs in, the distinct ID is used as the user's identifier. Note: The distinct ID changes when the user reinstalls the app or switches devices.

3.1 Set the account ID

When a user logs in, you can call Login to set the user's account ID. The AE platform uses the account ID as the identifier, and the account ID you set is kept until Logout is called. Calling Login multiple times overwrites the previous account ID.

// The unique login identifier of the user, which corresponds to #account_id in the reported data. In this case, the value of #account_id is TA
UTDAnalytics::Login("TA");

You can call Login multiple times. Each call checks whether the account ID passed in matches the previously saved ID. If they match, the call is ignored; otherwise, the previous ID is overwritten.

This method does not upload a login event

3.2 Set super properties

Super properties are properties that every event carries. You can call SetSuperProperties to set super properties. We recommend setting super properties before you send events. Some important properties, such as a user's membership level and source channel, need to be set in every event; in this case, you can set them as super properties.

    TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
    Properties->SetStringField("channel", "ta");//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);//Object group

    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 is the name of the property and is of the string type. It must start with a letter, can contain only digits, letters, and underscores "_", and can be up to 50 characters long. Keys are not case-sensitive; AE converts all letters to lowercase
Value is the value of the property. Supported types are string, number, Boolean, time, object, object group, and array

Event properties and user properties have the same requirements as super properties

3.3 Enable auto-tracking

The following code example enables the install, start, and end events (auto-tracking isn't supported on PC). To learn more about the SDK's auto-tracking capabilities, see Auto-tracked events

// Enable auto-tracking
UTDAnalytics::EnableAutoTrack();

3.4 Send events

You can call Track to upload events. We recommend setting event properties and the conditions for sending them according to the tracking plan you prepared earlier. The following example tracks a user purchasing a product:

TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("product_name", "Product Name");//String
// Report an event with properties
UTDAnalytics::Track("product_buy", Properties);

The event name is of the string type. It must start with a letter, can contain digits, letters, and underscores "_", and can be up to 50 characters long.

3.5 Set user properties

For general user properties, you can call UserSet to set them. Properties uploaded through this API overwrite the existing property values. If the user property did not exist before, it is created with the same type as the value passed in. The following example sets the user name.

 //At this point, "username" is "TA"
TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
Properties->SetStringField("username", "TA");//String
UTDAnalytics::UserSet(Properties);
//At this point, "username" is "AE"
TSharedPtr<FJsonObject> NewProperties = MakeShareable(new FJsonObject);
NewProperties->SetStringField("username", "AE");//String
UTDAnalytics::UserSet(NewProperties);

4. Best practices

The following sample code includes all of the operations above. We recommend using them in the following order:

#include "TDAnalytics.h"
if (isPrivacyPolicyAccepted) { // The user has accepted the Privacy Policy
   //Initialize the SDK
   UTDAnalytics::Initialize();
   // Enable auto-tracked events
   UTDAnalytics::EnableAutoTrack();
   //If the user has logged in, you can set the user's account ID as the unique identifier
   UTDAnalytics::Login("TA");
   //Set super properties
   TSharedPtr<FJsonObject> Properties = MakeShareable(new FJsonObject);
   Properties->SetStringField("channel", "ta");//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);//Object group

   TArray< TSharedPtr<FJsonValue> > DataArray;
   TSharedPtr<FJsonValueString> DataValue = MakeShareable(new FJsonValueString("data_value"));
   DataArray.Add(DataValue);
   Properties->SetArrayField("arr", DataArray);//Array
   UTDAnalytics::SetSuperProperties(Properties, AppID);
   //Send an event
   TSharedPtr<FJsonObject> EventProperties = MakeShareable(new FJsonObject);
   EventProperties->SetStringField("product_name", "Product Name");//String
   UTDAnalytics::Track("product_buy", EventProperties);
   //Set user properties
   TSharedPtr<FJsonObject> UserProperties = MakeShareable(new FJsonObject);
   UserProperties->SetStringField("username", "TA");//String
   UTDAnalytics::UserSet(UserProperties);
}

Was this page helpful?

1. Integrate the SDK​

1.1 Integrate the TDAnalytics plugin​

1.2 Activate the TDAnalytics plugin​

2. Initialization​

3. Common features​

3.1 Set the account ID​

3.2 Set super properties​

3.3 Enable auto-tracking​

3.4 Send events​

3.5 Set user properties​

4. Best practices​