Auto-tracking

Last updated 10/03/2026

1. Enable auto-tracked events

You can call enableAutoTrack and pass in a TDAutoTrackEventType type to enable auto-tracking. Six types are currently supported:

• ta_app_start: the app enters the foreground. The corresponding type is TDAutoTrackEventType.APP_START
• ta_app_end: the app enters the background. The corresponding type is TDAutoTrackEventType.APP_END
• ta_app_install: the app is opened for the first time after installation. The corresponding type is TDAutoTrackEventType.APP_INSTALL
• ta_app_crash: the app crashes because of an uncaught exception. The corresponding type is TDAutoTrackEventType.APP_CRASH
• ta_app_view: triggered when the app navigates between routes with Navigator. The corresponding type is TDAutoTrackEventType.APP_VIEW_SCREEN
• ta_app_click: the app control click event is triggered when the user clicks a control. The corresponding type is TDAutoTrackEventType.APP_CLICK

Note the following about auto-tracked events:

1. Auto-tracked events are implemented in the native SDK, so dynamic super properties currently can't be added to auto-tracked events.
2. If you need to set the distinct ID or super properties, set them before you enable auto-tracked events.

Example of enabling auto-tracking:

TDAnalytics.enableAutoTrack(TDAutoTrackEventType.APP_START |
    TDAutoTrackEventType.APP_END |
    TDAutoTrackEventType.APP_INSTALL |
    TDAutoTrackEventType.APP_CRASH |
    TDAutoTrackEventType.APP_CLICK |
    TDAutoTrackEventType.APP_VIEW_SCREEN);

2. Details

2.1 Page view event

Triggered when the app navigates between routes with Navigator. Details of the event are as follows:

• Event name: ta_app_view

• Preset properties:

  #screen_name: string, page name

  #title: string, page title

  #referrer: string, referrer address

• Steps to enable:

  • Add a global listener: add navigatorObservers under MaterialApp

  import 'package:thinking_analytics/autotrack/td_page_view.dart';
  
  void main() => runApp(new MaterialApp(
      navigatorObservers: TDNavigatorObserver.wrap([]), home: MyApp()));

  • Call enableAutoTrack to enable it. The sample code is as follows:

  TDAnalytics.enableAutoTrack(TDAutoTrackEventType.APP_VIEW_SCREEN,
      autoTrackEventProperties: {
        "test_property": "test_property_value"
      },
      autoTrackPageConfig: TDAutoTrackConfig(
        pageConfigs: [
          TDAutoTrackPageConfig<Page1>(
            screenName: "Page1",
            title: "First page",
          ),
          TDAutoTrackPageConfig<Page2>(
            screenName: "Page2",
            title: "Second page",
            ignore: false,
            properties: {
              "multi_property": "multi_property_value"
            },
          )
        ],
  ));

autoTrackEventProperties: sets super properties for auto-tracked events

autoTrackPageConfig: configuration related to page views. You can customize the title and screenName of each page. ignore specifies whether to skip collection for the page, and properties are the custom properties of the page

note

Enable it as early as possible. Otherwise, the lifecycle of the first page has already passed, and the view event of the first page can't be collected

2.2 Element click event

The app control click event is triggered when the user clicks a control

• Event name: ta_app_click

• Preset properties:

  #screen_name: string, page name

  #title: string, page title

  #element_type: string, element type

  #element_content: string, element content

• Steps to enable

TDAnalytics.enableAutoTrack(TDAutoTrackEventType.APP_CLICK);

• Custom properties for controls

Customize properties by setting TDElementKey

• First parameter: element ID, which corresponds to the property #element_id
• properties: custom properties
• isIgnore: whether to ignore auto-tracked events for this control

import 'package:thinking_analytics/autotrack/td_autotrack_config.dart';

ElevatedButton(
    key: TDElementKey("Element ID", properties: {"key": "value"},isIgnore: true),
    onPressed: () {},
    child: Text(
      "Button 2",
      style: TextStyle(fontSize: 14),
    )),

3. Set super properties for auto-tracked events

When you call enableAutoTrack, you can set custom properties through the autoTrackEventProperties parameter

TDAnalytics.enableAutoTrack(TDAutoTrackEventType.APP_START,
    autoTrackEventProperties: {
  'auto_test': 'stu',
  'auto_arr': [1, 2, 3],
  'auto_obj': {'obj_test': 'xxx'}
});