Auto-tracking

Last updated 10/03/2026

1. Enable auto-tracked events

tip

This feature is temporarily disabled on the HarmonyOS platform

You can call EnableAutoTrack and pass in TDAutoTrackEventType to enable auto-tracking for the specified events.

public enum TDAutoTrackEventType
{
    None = 0,
    AppStart = 1 << 0,
    AppEnd = 1 << 1,
    AppCrash = 1 << 4,
    AppInstall = 1 << 5,
    AppSceneLoad = 1 << 6,
    AppSceneUnload = 1 << 7,
    All = AppStart | AppEnd | AppInstall | AppCrash | AppSceneLoad | AppSceneUnload
}

The auto-tracked events are described below:

• AppStart: ta_app_start is reported when the game enters the foreground. The preset property #resume_from_background indicates whether this launch is a resume.

tip

Note: In WeChat mini games, the AppStart event becomes the show event, with the event name ta_mg_show and the additional property start_reason

• AppEnd: ta_app_end is reported when the game enters the background. The preset property #duration indicates how long the game stayed in the foreground this time, in seconds.

tip

Note: In WeChat mini games, the AppEnd event becomes the hide event, with the event name ta_mg_hide

• AppCrash: ta_app_crash is reported when an uncaught exception occurs. Currently, on the Android platform, uncaught exceptions of the virtual machine are handled. On the iOS platform, Unix signal exceptions and NSException exceptions are handled.
• AppInstall: ta_app_install is reported when the app is opened after it is installed for the first time. Uninstalling and reinstalling is not distinguished. This event is reported only once after installation and is not reported again after later updates.

tip

Note: In WeChat mini games, the AppInstall event becomes the launch event, with the event name ta_mg_launch and the additional property start_reason

• AppSceneLoad: ta_scene_loaded is reported when a game scene (Scene) is loaded
• AppSceneUnload: ta_scene_unloaded is reported when a game scene (Scene) is unloaded

You can pass in TDAutoTrackEventType.All to enable all currently supported auto-tracked events, or enable only some of them based on your project's needs.

// Enable all auto-tracked events
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All);

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

Note: If you need to set a custom distinct ID or super properties, do so before you enable auto-tracked events. Auto-tracked events currently do not support dynamic super properties.

For AppCrash, if you want to collect only Objective-C and Java exceptions but not C# exceptions on the iOS and Android platforms, in v2.3.1 and later you can add ta_public_config.xml to the Resources directory to configure the switch, as follows:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- ThinkingAnalytics disable C# Exception -->
    <bool name="DisableCSharpException">true</bool>
</resources>

2. Set custom properties for auto-tracked events

Starting from v2.2.4, when you call EnableAutoTrack to enable auto-tracking, you can also pass in the custom properties to collect.

// Enable auto-tracked events and set custom properties
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All, new Dictionary<string, object>() {
    {"custom_key", "custom_value"}
});

You can also call SetAutoTrackProperties to specify custom properties for specific auto-tracked events.

Note: SetAutoTrackProperties does not enable the collection of auto-tracked events. Use it together with the EnableAutoTrack method.

// Set custom properties for a single auto-tracked event
TDAnalytics.SetAutoTrackProperties(TDAutoTrackEventType.AppStart, new Dictionary<string, object>() 
{
    {"start_key", "start_value"}
});

// Set custom properties for multiple auto-tracked events
TDAnalytics.SetAutoTrackProperties(TDAutoTrackEventType.AppInstall | TDAutoTrackEventType.AppStart, new Dictionary<string, object>() 
{
    {"install_crash_key", "install_crash_value"}
});

// Enable all auto-tracked events
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All);

3. Set the auto-tracked event callback

Starting from v2.4.0, you can set an auto-tracked event callback to set custom properties in real time or run custom code when the corresponding event is triggered. To set the auto-tracked event callback, first create a class that implements the TDAutoTrackEventHandler interface and override the public Dictionary<string, object> GetAutoTrackEventProperties(int type, Dictionary<string, object>properties) method. The return value of this method is the auto-tracked event properties to set. Then call EnableAutoTrack and pass in the auto-tracked event callback object, as follows:

// 1. Implement the auto-tracked event callback
public class AutoTrackECB : TDAutoTrackEventHandler
{
    public Dictionary<string, object> GetAutoTrackEventProperties(int type, Dictionary<string, object>properties)
    {
        return new Dictionary<string, object>() 
        {
            {"AutoTrackEventProperty", DateTime.Today}
        };
    }
}
// 2. Enable auto-tracking and set the event callback
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All, new AutoTrackECB());

4. Enable auto-tracked scene events

Starting from v2.4.1, auto-tracking of scene load and unload events is supported.

Register delegates for scene load and unload to enable auto-tracked scene events.

We recommend calling this in the OnEnable method of a MonoBehaviour script.

    private void OnEnable()
    {
        // Listen for scene load and unload events
        SceneManager.sceneLoaded += TDAnalytics.OnSceneLoaded;
        SceneManager.sceneUnloaded += TDAnalytics.OnSceneUnloaded;
    }

Starting from v2.5.1, you can call the EnableAutoTrack method to enable auto-tracked scene events

// Enable all auto-tracked events
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.All);

// Enable auto-tracking of the scene load and scene unload events
TDAnalytics.EnableAutoTrack(TDAutoTrackEventType.AppSceneLoad | TDAutoTrackEventType.AppSceneUnload);