Skip to main content

Unity SDK user guide (legacy versions)

Last updated 10/03/2026

The Unity SDK has been upgraded to v2.0.0. This guide is for legacy versions. For new integrations, see the latest Unity SDK user guide

This guide describes how to integrate the Unity SDK into your project. Before you start, we recommend that you read the Data rules chapter. You can get the source code of the Unity SDK on GitHub.

Latest version: v1.4.4

Update time: 2020-04-17

Download

1. Initialize the SDK​

1.1 Integrate the SDK​

  1. Download the Unity SDK resource file and import it into your project: Assets > Import Package > Custom Package, and then select the file you just downloaded

Note: The Android plugin is integrated through Gradle, so only Unity 5.4 and later are currently supported.

  1. Add the ThinkingAnalytics GameObject and configure the SDK

The settings in the image above are as follows:

Configuration

  • 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: Sets the network conditions under which data is reported to the server. The default is DEFAULT. The available options are as follows:

    • DEFAULT: Reports data on 3G, 4G, 5G, and Wi-Fi networks
    • WIFI: Reports data only on Wi-Fi networks
    • ALL: Reports data on 2G, 3G, 4G, 5G, and Wi-Fi networks

  • Postpone Track: Specifies whether to postpone reporting. If enabled, data is reported only after StartTrack() is called. Before that, data is cached until StartTrack() is called. If you need to set the distinct ID or super properties, we recommend that you enable this option. For how to call it, see Delayed reporting

Tokens

Each Token represents one instance. To report data to multiple projects, click + in the lower-right corner to add project settings. For notes on multiple projects, see "Multi-project support" at the end of this section. 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. For details, see SDK modes.

  • Auto Track: Specifies whether to enable auto-tracked events. If selected, the SDK automatically records game starts and closes. For details, see Auto-tracked events

  • TimeZone: Supported since v1.4.3. The default time zone that data is aligned to. Currently, this setting applies only to the event time and the time of user property settings, and doesn't apply to DateTime values in properties.

Note: Because some devices block plaintext transmission by default, we strongly recommend using an HTTPS receiver URL.

Multi-project support​

When you configure the SDK, you can add multiple APP IDs. Then, when you call an API, append a parameter at the end to specify the APP ID. The following example uses the Identify() API:

// Set the distinct ID for the instance whose APP ID is "debug-appid"
ThinkingAnalyticsAPI.Identify("unity_debug_id", "debug-appid");

Note: The distinct ID, account ID, super properties, and so on aren't shared across projects. You need to set them separately for each APP ID instance.

If you don't append an APP ID parameter, the first APP ID instance in the list (the instance marked default after its Token ID) is used by default. You can drag list items to reorder the list and change the default APP ID instance.

1.2 Use the SDK​

After you configure the SDK, you can start using it to upload events. We also provide a Sample for your reference.

using ThinkingAnalytics;

ThinkingAnalyticsAPI.Track("unity_start");

2. Set user IDs​

After you start using the Unity SDK, it uses a random UUID as each user's distinct ID by default. This ID identifies the user while the user isn't logged in. Note that the default distinct ID changes when the user reinstalls the game or switches devices.

2.1 Set the distinct ID (optional)​

If your game has its own distinct ID management system for users, you can call Identify to set the distinct ID:

ThinkingAnalyticsAPI.Identify("unity_id");

To get the distinct ID, call GetDistinctId:

ThinkingAnalyticsAPI.GetDistinctId();

2.2 Set and clear the account ID​

When a user logs in, you can call Login to set the user's account ID. After the account ID is set, it is used as the user's identifier, and it is retained until you call Logout:

// Set the account ID
ThinkingAnalyticsAPI.Login("unity_user");

// Clear the account ID
ThinkingAnalyticsAPI.Logout();

Note: This method doesn't upload user login or logout events.

3. Upload events​

You can call ThinkingAnalyticsAPI.Track() to report events and their properties. In general, you may need to upload a dozen to hundreds of different events. If you are using the AE backend for the first time, we recommend that you upload a few key events first.

3.1 Upload events​

We recommend setting event properties and the conditions for sending events based on the document you prepared earlier. The event name is of string type. It must start with a letter, can contain digits, letters, and underscores "_", can be up to 50 characters long, and is case-insensitive.

Dictionary<string, object> properties = new Dictionary<string, object>()
    {
        {"KEY_DateTime", DateTime.Now.AddDays(1)},
        {"KEY_STRING", "B1"},
        {"KEY_BOOL", true},
        {"KEY_NUMBER", 50.65}
    };
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties);
  • Event properties are of the Dictionary<string, object> type, where each element represents one property;
  • The event property Key is the property name and is of string type. It must start with a letter, can contain digits, letters, and underscores "_", can be up to 50 characters long, and is case-insensitive.
  • Property values support five types: string, numeric, bool, DateTime, and List.

Note: The List type is supported since v1.4.0. Its elements are all converted to strings before they are stored.

When you call Track(), the SDK uses the current system time as the time the event occurred. To specify the event time, you can pass a DateTime parameter to set the event trigger time. Starting from v1.3.0, the SDK can upload the time offset of the event based on DateTimeKind (corresponding to the preset property #zone_offset). However, if the Kind property of the DateTime you pass is DateTimeKind.Unspecified, the time offset isn't reported:

DateTime dateTime = DateTime.Now.AddDays(-1);
ThinkingAnalyticsAPI.Track("TEST_EVENT", properties, dateTime);

Starting from v1.4.3, you can configure the default time zone of an SDK instance. If you configure a time zone other than Local, all event times are aligned to that time zone, and the Kind property of the DateTime you pass is ignored.

Note: Although you can set the trigger time of an event, the receiver applies the following limit: it accepts only data from 10 days before to 3 days after the server time. Data outside this range is treated as abnormal, and the entire record can't be stored.

3.2 Set static super properties​

Some important properties, such as the player's server and channel, need to be set in every event. In this case, you can set them as 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.

Dictionary<string, object> superProperties = new Dictionary<string, object>()
    {
        {"SERVER", 0},
        {"CHANNEL", "A3"}
    };
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

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 upload a super property that was set before, the new value overwrites the previous one. If a super property and a property uploaded through Track() have the same Key, the event's property overwrites the super property.

To delete a super property, call UnsetSuperProperty() to clear it. To clear all super properties, call ClearSuperProperties().

// Clear the super property named CHANNEL
ThinkingAnalyticsAPI.UnsetSuperProperty("CHANNEL");

// Clear all super properties
ThinkingAnalyticsAPI.ClearSuperProperties();

3.3 Set dynamic super properties​

If the value of a super property isn't constant, you can set it as a dynamic super property. Dynamic super properties are also added to all events, and their actual values are obtained dynamically when events are reported.

To set dynamic super properties, first create a dynamic super property class that implements the IDynamicSuperProperties interface, and override the public Dictionary<string, object> GetDynamicSuperProperties() method. The return value of this method is the dynamic super properties to set. Then call SetDynamicSuperProperties and pass in the dynamic super property object. Example:

using ThinkingAnalytics;

// Define the dynamic super property implementation. This example sets a dynamic super property for the UTC time
public class DynamicProp : IDynamicSuperProperties
{
    public Dictionary<string, object> GetDynamicSuperProperties()
    {
        return new Dictionary<string, object>() {
            {"KEY_UTCTime", DateTime.UtcNow}
        };
    }
}

ThinkingAnalyticsAPI.SetDynamicSuperProperties(new DynamicProp());

Note: If event properties have the same name, dynamic super properties take precedence over super properties, but have lower priority than the event properties set in Track.

3.4 Record event duration​

To record how long an event lasts, call TimeEvent() to start timing and specify the name of the event you want to time. When you upload that event, the #duration property is automatically added to its event properties to indicate the recorded duration, in seconds.

// Call TimeEvent to start timing the TIME_EVENT event
ThinkingAnalyticsAPI.TimeEvent("TIME_EVENT");

// do some thing...

// When the TIME_EVENT event is uploaded through Track, the #duration property is added to its properties
ThinkingAnalyticsAPI.Track("TIME_EVENT");

4. User properties​

The user property APIs that AE currently supports are UserSet, UserSetOnce, UserAdd, UserUnset, UserDelete, and UserAppend.

4.1 UserSet​

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.

ThinkingAnalyticsAPI.UserSet(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", 0},
        {"USER_PROP_STRING", "A3"}
    });

Similar to event properties:

  • User properties are of the Dictionary<string, object> type, where each element represents one property;
  • The user property Key is the property name and 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. It isn't case-sensitive;
  • User property values support five types: string, numeric, bool, DateTime, and List.

Note: The List type is supported since v1.4.0. Its elements are all converted to strings before they are stored.

4.2 UserSetOnce​

If a user property only needs to be set once, you can call UserSetOnce to set it. If the property already has a value, this call is ignored:

ThinkingAnalyticsAPI.UserSetOnce(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", -50},
        {"USER_PROP_STRING", "A3"}
    });

Note: User properties set through UserSetOnce have the same types and restrictions as those set through UserSet.

4.3 UserAdd​

When you upload a numeric property, you can call UserAdd to accumulate its value. If the property has not been set yet, it is assigned 0 before the calculation. You can pass a negative value, which is equivalent to subtraction.

ThinkingAnalyticsAPI.UserAdd(new Dictionary<string, object>()
    {
        {"USER_PROP_NUM", -100.9},
        {"USER_PROP_NUM2", 10.0}
    });

Note: The property types and Key restrictions in UserAdd are the same as in UserSet, but Value accepts only numeric properties.

4.4 UserUnset​

If you need to reset a property of a user, you can call UserUnset to clear the value of the specified user property. This API accepts a string or a list as the parameter:

// Delete a single user property
ThinkingAnalyticsAPI.UserUnset("userPropertyName");

// Delete multiple user properties
List<string> listProps = new List<string>();
listProps.Add("aaa");
listProps.Add("bbb");
listProps.Add("ccc");

ThinkingAnalyticsAPI.UserUnset(listProps);

4.5 UserDelete​

To delete a user, you can call UserDelete. After that, you can no longer query this user's user properties, but the events generated by the user can still be queried.

ThinkingAnalyticsAPI.UserDelete();

4.6 UserAppend​

Starting from v1.4.0, you can call UserAppend to append elements to user properties of the List type:

List<string> stringList = new List<string>();
stringList.Add("apple");
stringList.Add("ball");
stringList.Add("cat");

// Append 3 elements to the user property named USER_LIST
ThinkingAnalyticsAPI.UserAppend(new Dictionary<string, object>
    {
        {"USER_LIST", stringList }
    });

5. Auto-tracked events​

If you selected the Auto Track option when you configured the SDK, the SDK automatically records:

  • ta_app_start: The game start event, triggered each time the user gains focus (that is, is in the game)
  • ta_app_end: The game close event, triggered when the game enters the Pause state. It carries the #duration property, which records the duration of this game session (in seconds)

Starting from version 1.1.0, you can collect the install event by calling an API:

// Collect the app install event
ThinkingAnalyticsAPI.TrackAppInstall();
  • ta_app_install: The game install event. It is triggered only when the user opens the app for the first time after installation. Upgrading the app doesn't trigger it, but deleting and reinstalling the app triggers it again.

6. Other configuration options​

6.1 Get the device ID​

After initialization, the SDK automatically generates a device ID and stores it in the local cache. For the same app or game, the device ID of a device doesn't change. You can call GetDeviceId() to get the device ID:

ThinkingAnalyticsAPI.GetDeviceId();

// Use the device ID as the distinct ID
// ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());

6.2 Delayed reporting​

If you selected the Postpone Track option, all reporting requests (including user property settings and event tracking) are cached until you call the following method:

ThinkingAnalyticsAPI.StartTrack();

Data starts being reported only after this API is called. Data generated before this API is called is reported with the newly set user ID and with super properties added. Therefore, if you set the user ID and super properties before you call StartTrack(), they apply to all data. This is suitable for scenarios where you need to set the distinct ID and super properties:

//Set the distinct ID
ThinkingAnalyticsAPI.Identify(ThinkingAnalyticsAPI.GetDeviceId());

//Set super properties
Dictionary<string, object> superProperties = new Dictionary<string, object>()
    {
        {"SERVER", 0},
        {"CHANNEL", "A3"}
    };
ThinkingAnalyticsAPI.SetSuperProperties(superProperties);

//Call the API that starts reporting
ThinkingAnalyticsAPI.StartTrack();

6.3 Pause or stop data reporting​

In v1.2.0, the SDK added the ability to stop reporting data. There are two types of APIs that stop SDK reporting:

  1. Pause SDK reporting (EnableTracking)

In some scenarios, you may want to temporarily stop the SDK's data collection and reporting, for example, when the user is in a test environment or has logged in with a test account. In this case, you can call the following API to temporarily stop SDK reporting.

You can call EnableTracking on an instance (including the main instance and light instances) and pass false to pause SDK reporting. The #distinct_id, #account_id, super properties, and so on that the instance has set are retained. Data that the instance has collected but not yet reported successfully continues to be retried. After that, the instance can't collect or report any new data, or set the distinct ID, account ID, super properties, and so on. However, it can still read the super properties, device ID, distinct ID, account ID, and other information that the instance has set.

The stopped state of an instance is saved in the local cache until you call EnableTracking and pass true, at which point the SDK instance resumes data collection and reporting. Note that light instances aren't cached, so their paused state isn't retained after the app is reopened, and reporting resumes.

// Pause reporting for the default instance. Cached data and settings aren't cleared
ThinkingAnalyticsAPI.EnableTracking(false);

// Resume reporting for the default instance
ThinkingAnalyticsAPI.EnableTracking(true);
  1. Stop SDK reporting (OptOutTracking)

In some special scenarios, you may need to stop the SDK completely. For example, in regions where GDPR applies, if a user chooses not to grant data collection permission, you can call the following API to turn off the SDK completely.

OptOutTracking can only be called on the main instance. The biggest difference from EnableTracking is that it clears the instance's local cache, including the instance's distinct ID, account ID, super properties, and the queue of unreported data. It then turns off collection and reporting for the instance.

// Stop reporting for the default instance and clear the local cache
ThinkingAnalyticsAPI.OptOutTracking();

If you want to delete the user's data in the AE cluster when you turn off the SDK, call OptOutTrackingAndDeleteUser. Before the SDK instance stops, this reports a UserDelete record to delete the user's user data.

// Stop reporting for the default instance and send user_del
ThinkingAnalyticsAPI.OptOutTrackingAndDeleteUser();

The stopped state of the instance is also saved in the local cache until you call OptInTracking. After that, reporting can continue, but the instance is then equivalent to a brand-new instance

// Re-enable reporting
ThinkingAnalyticsAPI.OptInTracking();

6.4 Create a light instance​

You can use light instances to create multiple instances under the same APP ID

// Create a light instance. Returns the light instance's token (similar to an APP ID)
string lightToken = ThinkingAnalyticsAPI.CreateLightInstance();

// Set the account ID for the light instance
ThinkingAnalyticsAPI.Login("anotherAccount", lightToken);

// Report an event through the light instance
ThinkingAnalyticsAPI.Track("TEST_EVENT", lightToken);

Note: A child light instance shares the APP ID, reporting URL, and some settings with its parent instance, but other information isn't shared

6.5 SDK run modes​

Starting from v1.4.0, the SDK can run in three modes:

  • NORMAL: Normal mode. Data is cached and reported according to a caching policy
  • DEBUG: Debug mode. Data is reported one record at a time. When problems occur, the user is notified through logs and exceptions
  • DEBUG_ONLY: Debug Only mode. Data is only validated and isn't stored

Note: DEBUG mode is only for data validation during integration. Don't use it in production mode.

To prevent Debug mode from going live in the production environment, Debug mode can only be enabled on specified devices. Debug mode can be enabled only on devices that have Debug mode enabled on the client and whose device IDs have been added on the Data → Tracking → Debugger page in the AE backend. To add a device, click Add test device in the upper-right corner of the page, click New device in the Select device drawer, and enter the device ID.

You can get the device ID in the following three ways:

  • The #device_id property in the event data in AE
  • Client logs: The SDK prints the DeviceId after initialization completes
  • Through an instance API call: Get the device ID

Release Note​

v1.4.4 2020/04/17​

  • Fixed a format error for the Double type when a custom CultureInfo is used

v1.4.3 2020/03/19​

  • Supported setting the default time zone for the #time property of data
  • Updated the native SDK versions

v1.4.2 2020/02/21​

  • Updated the iOS plugin to fix a bug introduced on older iOS versions

v1.4.1 2020/02/14​

  • Adapted to Unity 2019.3.1f1

v1.4.0 2020/02/11​

  • Property values support the List / Array types
  • Added the UserAppend API
  • Supported data validation in Debug mode
  • Supported configuring a separate receiver URL for each instance
  • Removed local data format validation

v1.3.1 2019/12/25​

  • Fixed an exit timeout on Android versions earlier than 4.3
  • Fixed an error when the iOS development environment isn't included

v1.2.0 2019/09/02​

  • Supported turning data reporting off and on
  • Supported pausing and resuming data reporting
  • Supported lightweight instances
  • Fixed a failure to set the network type in version 2019.2.1f
  • Fixed inaccurate timeEvent timing
  • Upgraded the Android/iOS SDK to 2.1.0

v1.1.0 2019/08/09​

  • Supported getting the device ID
  • Supported dynamic super properties
  • Supported install event collection
  • Upgraded the embedded Android SDK to 2.0.2
  • Upgraded the embedded iOS SDK to 2.0.1
  • Supported a reporting cache option. You can choose to call StartTrack() to start reporting

v1.0.0 2019/06/20​

  • Added support for setting the distinct ID and the user account ID
  • Added support for reporting events and user properties
  • Supported automatic reporting of the ta_app_start and ta_app_end events
  • Supported the super properties API
  • Supported the timeEvent API
  • Supported reporting to multiple projects
Was this page helpful?
On this page