Skip to main content

Unity

Last updated 10/05/2026
tip

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

Unity SDK: Supports game platforms such as iOS, Android, HarmonyOS, Unity Editor, Windows, Mac, WebGL, Switch, Xbox, and PS4/5, as well as mini game platforms such as WeChat mini games, Douyin mini games, and OPPO mini games

Requires Unity 5.4.0 or later. The SDK is about 320 KB in size

Latest version: v3.5.3

Update time: 2026-09-22

Downloads: Source code, SDK download

Note

This document applies to v3.0.0 and later. For earlier versions, see Unity Integration Guide (V2) and SDK download (v2.6.1)

1. Integrate the SDK​

1.1 Manual integration​

  1. Download the Unity SDK resource files
  2. Double-click the ta_unity_sdk.unitypackage file, or use Assets > Import Package > Custom Package to import ta_unity_sdk.unitypackage
note

When you upgrade the unitypackage from 3.3.0 to 3.4+.x, delete the original SDK before you import the new one

Reason: When Unity or Tuanjie Engine exports to the HarmonyOS platform, .ts files are occasionally lost. All .ts files have therefore been renamed to .tslib. If you don't delete the original files, duplicate file names occur

1.2 Package Manager integration​

Starting from v2.4.1, you can integrate the SDK automatically through Package Manager.

  1. Open the Window - Package Manager menu
  2. Click +, and then select Add package from git URL...
  3. Enter https://github.com/ThinkingDataAnalytics/unity-sdk.git, click Add, and wait for loading to complete

2. Initialization​

We recommend initializing the SDK manually. Automatic initialization through a prefab is also available.

2.1 Manual initialization​

using ThinkingData.Analytics;
//Initialization method 1
TDAnalytics.Init("APPID","SERVER");
//Initialization method 2
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);

2.2 Automatic initialization​

tip

When you integrate the SDK through Package Manager integration, only some settings are supported. Refer to the actual options.

  1. Add the TDAnalytics prefab and configure the SDK

The settings in the image above are as follows:

Configuration

  • Start Manually: Specifies whether to initialize the SDK manually

    1. If enabled, you need to call TDAnalytics.Init() manually to initialize the SDK.
    2. If disabled, the SDK is initialized automatically when the TDAnalytics prefab loads.

  • Enable Log: Specifies whether to enable logging. If enabled, the SDK prints the reporting status to help you debug. You can also check whether events are reported correctly in Editor mode. Properties that don't meet the requirements are shown in the console as warning logs.

  • Network Type: The network condition for reporting data. The default is All, which reports data on any network. If you select Wifi, data is reported only on Wi-Fi networks. This setting takes effect only on iOS, Android, and HarmonyOS, and has no effect on PC, WebGL, or mini games.

Configs

Each Config represents one instance. To report data to multiple projects, click + in the lower-right corner to add project settings. You can add multiple Token settings with different APP IDs.

  • APP ID: Required. The APP_ID of your project, which is provided when you apply for the project. Enter it here.

  • SERVER URL: Required. The URL of the data receiver:

  • MODE: The running mode of the SDK instance. Make sure you use NORMAL mode in the production environment.

  • TimeZone: The default time zone of the SDK instance, used to align event times. It works the same as Set the default time zone in the advanced guide. The default is Local (the device's local time zone). Other options are UTC, Asia_Shanghai, Asia_Tokyo, America_Los_Angeles, and America_New_York. If you select Other, enter the time zone ID in the input box on the right.

Note: Some devices block plaintext transmission by default, so we strongly recommend that you use an HTTPS receiver URL

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. AE uses the account ID as the identifier, and the account ID is retained until you call Logout. 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
TDAnalytics.Login("TA");

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.

Dictionary<string, object> superProperties = new Dictionary<string, object>();
superProperties["channel"] = "ta";//String
superProperties["age"] = 1;//Number
superProperties["isSuccess"] = true;//Boolean
superProperties["birthday"] = DateTime.Now;//Time
superProperties["object"] = new Dictionary<string, object>(){{ "key", "value"}};//Object
superProperties["object_arr"] = new List<object>() {new Dictionary<string, object>(){{ "key", "value" }}};//Object group
superProperties["arr"] = new List<object>() { "value" };//Array
TDAnalytics.SetSuperProperties(superProperties);//Set super properties

Super properties are saved in the cache, so you don't need to call this every time the app starts. If you call SetSuperProperties to set a super property that was set before, the new value overwrites the previous one.

  • Event properties are of the Dictionary<string, object> type, where each element represents one property
  • 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. To learn more about the SDK's auto-tracking capabilities, see Auto-tracked events

note

This feature is temporarily disabled on the HarmonyOS platform

//Enable auto-tracking of the install, start, and end events
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);

3.4 Send events​

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

Dictionary<string, object> properties = new Dictionary<string, object>(){{"product_name", "Product Name"}};
TDAnalytics.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.

//username is now TA
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
//username is now AE
TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TE"}});

4. Best practices​

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

using ThinkingData.Analytics;
if (user has accepted the privacy policy)
{  // Initialize the SDK
   TDAnalytics.Init("APPID", "SERVER");
   //Enable auto-tracked events
   TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart | TDAutoTrackEventType.AppEnd);
   //If the user has logged in, you can set the user's account ID as the unique identifier
   TDAnalytics.Login("TA");
   //After super properties are set, every event carries them
   Dictionary<string, object> superProperties = new Dictionary<string, object>();
   superProperties["channel"] = "ta";//String
   superProperties["age"] = 1;//Number
   superProperties["isSuccess"] = true;//Boolean
   superProperties["birthday"] = DateTime.Now;//Time
   superProperties["object"] = new Dictionary<string, object>(){{ "key", "value"}};//Object
   superProperties["object_arr"] = new List<object>() {new Dictionary<string, object>(){{ "key", "value" }}};//Object group
   superProperties["arr"] = new List<object>() { "value" };//Array
   TDAnalytics.SetSuperProperties(superProperties);//Set super properties
   //Send an event
   Dictionary<string, object> properties = new Dictionary<string, object>(){{"product_name", "Product Name"}};
   TDAnalytics.Track("product_buy", properties);
   //Set user properties
   TDAnalytics.UserSet(new Dictionary<string, object>(){{"user_name", "TA"}});
}
Was this page helpful?
On this page