Skip to main content

Auto-tracking

Last updated 10/05/2026

The Android SDK supports auto-tracking of events such as install, start, and end.

1. Introduction​

AE provides APIs for collecting data automatically. You can choose which data to collect automatically based on your business needs.

The following auto-tracked event types are currently supported:

  1. Install event: Records the installation of the APP
  2. Start event: Includes opening the APP and opening the APP from the background
  3. End event: Includes closing the APP and the APP moving to the background, and also collects the duration since start
  4. View event: The user views a page (Activity) in the APP
  5. Click event: The user clicks a control in the APP
  6. Crash event: Records crash information when the APP crashes

The following sections describe how each type of data is collected

2. Enable auto-tracking​

Call enableAutoTrack to enable auto-tracking:

//APP install event TDAnalytics.TDAutoTrackEventType.APP_INSTALL
//APP start event TDAnalytics.TDAutoTrackEventType.APP_START
//APP end event TDAnalytics.TDAutoTrackEventType.APP_END
//APP view page event TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN
//APP control click event TDAnalytics.TDAutoTrackEventType.APP_CLICK
//APP crash event TDAnalytics.TDAutoTrackEventType.APP_CRASH
//Enable auto-tracked events
TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_START | TDAnalytics.TDAutoTrackEventType.APP_END
        | TDAnalytics.TDAutoTrackEventType.APP_INSTALL | TDAnalytics.TDAutoTrackEventType.APP_VIEW_SCREEN | TDAnalytics.TDAutoTrackEventType.APP_CLICK
        | TDAnalytics.TDAutoTrackEventType.APP_CRASH);
tip

To collect control click events or Fragment view events, integrate the auto-tracking plugin. See Section 7 on this page.

3. Details​

3.1 Install event​

The APP install event records the actual installation of the APP and is reported when the APP starts. The event trigger time is the time of the first start after the APP is installed. Upgrading the APP doesn't trigger the install event, but deleting and reinstalling the APP reports an install event.

  • Event name: ta_app_install

3.2 Start event​

The APP start event is triggered when the user opens the APP or wakes the APP from the background. Details of the event are as follows:

  • Event name: ta_app_start
  • Preset property: #resume_from_background, Boolean, indicates whether the APP was opened by the user or woken from the background. true means it was woken from the background, and false means it was opened directly.
  • Note that starting from V2.8.1, the SDK by default no longer allows start events triggered by silent background starts (such as directly starting a background service or a push). To enable them, add the resource file ta_public_config.xml under res/values
<?xml version="1.0" encoding="utf-8"?>
<resources>
   <bool name="TAEnableBackgroundStartEvent">true</bool>
</resources>

3.3 End event​

The APP end event is triggered when the user closes the APP or moves the APP to the background. Details of the event are as follows:

  • Event name: ta_app_end
  • Preset property: #duration, number, indicates the duration of this APP visit (from start to end), in seconds.

3.4 View page event​

The APP view page event is triggered when the user views a page (Activity). Details of the event are as follows:

  • Event name: ta_app_view

  • Preset properties:

    #screen_name, string, the package name.class name of the Activity

    #title, string, the title of the Activity, whose value is the value of the title property of the Activity

You can add other properties to page view events to extend their analytical value. The following describes how to customize the properties of view page events

3.4.1 Enable auto-tracking of Fragment page view events​

For Fragments based on android.support.v4.app.Fragment, you can use the following method to automatically collect page view events:

After the SDK is initialized, call the following method to enable auto-tracking for Fragments

TDAnalytics.trackFragmentAppViewScreen();

For Fragments based on android.app.Fragment, you can trigger page view events yourself with the following method:

TDAnalytics.trackViewScreen(targetFragment);
  • Replace targetFragment with the Fragment for which you want to upload page view events

3.4.2 Customize the properties of page view events​

For Activity page view events, you can add properties by implementing the methods of the ScreenAutoTracker interface. With the following two methods, you can add page URL information and other custom properties to page view events:

public class MainActivity extends AppCompatActivity implements ScreenAutoTracker {
    private Context mContext;

    @Override
    public String getScreenUrl() {
        return "thinkingdata://page/main";
    }

    @Override
    public JSONObject getTrackProperties() throws JSONException {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("param1", "ABCD");
        jsonObject.put("param2", "thinkingdata");
        return jsonObject;
    }
}

The return value of getScreenUrl is used as the URL Schema of the Activity. When the view event of this page is triggered, the preset property #url is added, whose value is the URL Schema of the current page. The SDK also gets the URL Schema of the page before the jump. If it can be obtained, it is added to the preset property #referrer as the referrer address.

The return value of getTrackProperties is the custom properties of the page's view event, which are automatically added to the page's view event

For Fragment page view events, we provide two ways to add properties

  • Add properties with @ThinkingDataFragmentTitle
@ThinkingDataFragmentTitle(title = "myFragment")
public class ListViewFragment extends BaseFragment {
  // your fragment implementations
}
  • Implement the ScreenAutoTracker interface
  @Override
  public JSONObject getTrackProperties() {
      try {
          JSONObject properties = new JSONObject();
          properties.put("#title", "RecyclerViewFragment");
          return properties;
      } catch (JSONException e) {
          // ignore
      }
      return null;
  }

3.5 Click event​

The APP control click event is triggered when the user clicks a control (view)

  • Event name: ta_app_click

  • Preset properties:

    #screen_name, string, the package name.class name of the Activity that the control belongs to

    #title, string, the title of the Activity that the control belongs to, whose value is the value of the title property of the Activity

    #element_content, string, the content of the control

    #element_type, string, the type of the control

    #element_id, string, the ID of the control, which uses android:id by default

    #element_position, string, uploaded only when the control has a position

    #element_selector, string, the concatenation of the control's viewPath

For click events of Views on a page, you can set more properties in the following ways to extend their analytical value:

3.5.1 Customize the control ID​

The control ID uses android:id by default. If this attribute can't be obtained, or you want to customize the control ID, use the following method to override the #element_id property

TDAnalytics.setViewID(view,viewID);

For Dialog, use the following method:

//android.app.Dialog
TDAnalytics.setViewID(view,viewID);

Or

//android.support.v7.app.AlertDialog
TDAnalytics.setViewID(view,viewID);

The parameter view is the view whose control ID you want to set, and the parameter viewID is the control ID to set. When the click event of this control is uploaded, the value of #element_id is the value passed in here

3.5.2 Customize the properties of control click events​

Use the following method to add custom properties to the click events of a control (view):

TDAnalytics.setViewProperties(view,properties);

The parameter view is the view for which you want to set custom properties, and the parameter properties, of type JSONObject, contains the custom properties to set. These properties are added when the click event of this control is uploaded.

In addition, for ExpandableListView, ListView, and GridView, you can also add custom properties for clicks on an item by implementing interfaces in the Adapter.

  • ExpandableListView must implement the ThinkingExpandableListViewItemTrackProperties interface
public interface ThinkingExpandableListViewItemTrackProperties {
    /**
     * Adds properties when the item at groupPosition and childPosition is clicked
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * Adds properties when the item at groupPosition is clicked
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingGroupItemTrackProperties(int groupPosition) throws JSONException;
}
  • ListView and GridView must implement the ThinkingAdapterViewItemTrackProperties interface
public interface ThinkingAdapterViewItemTrackProperties {
    /**
     * Adds properties when the item at position is clicked
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingItemTrackProperties(int position) throws JSONException;
}

3.5.3 Add page (Activity) information to AlertDialog click events​

For click events of AlertDialog (android.app.AlertDialog and android.support.v7.app.AlertDialog), you can use the following method to bind the page (Activity) it belongs to. The #screen_name and #title properties of that page are then added to its click events.

  • If you show the dialog by calling dialog.show(), use the following method:
dialog.setOwnerActivity(targetActivity);
  • If you show the dialog by calling builder.show(), use the following method:
builder.show().setOwnerActivity(activity);

3.5.4 Upload control click events with the @ThinkingDataTrackViewOnClick annotation​

If you use android:onclick to add a click handler method to a control (view), you can add the annotation @ThinkingDataTrackViewOnClick to that method. When the method is executed, the SDK uploads a control click event

@ThinkingDataTrackViewOnClick
public void buttonOnClick(View v){}

If the method buttonOnClick is called, a control click event is uploaded

3.6 Crash event​

When an uncaught exception occurs in the APP, an APP crash event is reported

  • Event name: ta_app_crash
  • Preset property: #app_crashed_reason, string, records the stack trace at the time of the crash

4. Ignore auto-tracked events​

You can ignore the auto-tracked events of a page or control in the following ways

4.1 Ignore auto-tracked events of a page​

If you don't want to send auto-tracked events (including page view and control click events) for certain pages (Activity), use the following method to ignore them:

//Ignore a single page
TDAnalytics.ignoreAutoTrackActivity(MainActivity.class);
//Ignore multiple pages
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
TDAnalytics.ignoreAutoTrackActivities(classList);

You can also add the annotation @ThinkingDataIgnoreTrackAppViewScreen before an Activity or Fragment to ignore the page view events of that Activity or Fragment

//Ignore page view events of TestActivity
@ThinkingDataIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
    ...
}

Add the annotation @ThinkingDataIgnoreTrackAppViewScreenAndAppClick before an Activity to ignore the page view events of that Activity and the click events of controls on that page

//Ignore page view events of TestActivity and control click events on that page
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
    ...
}

4.2 Ignore click events of a control type​

To ignore the click events of a certain type of control, use the following method

TDAnalytics.ignoreViewType(ignoredClass);
  • ignoredClass is the control type to ignore, such as Dialog or Checkbox

4.3 Ignore click events of an element (View)​

To ignore the click events of a specific element (View), use the following method

TDAnalytics.ignoreView(targetView);
  • targetView is the View to ignore

5. Set up events quickly with annotations​

To monitor how many times a method is called, or to upload an event whenever a method is called, you can use the annotation @ThinkingDataTrackEvent to quickly set up the event to upload. Note that properties can't take variables, so this is suitable only for uploading simple events

//Use the annotation
@ThinkingDataTrackEvent(eventName = "event_name", properties = "{\"paramString\":\"value\",\"paramNumber\":123,\"paramBoolean\":true}")
public void fun(){}

If the method fun is called, an event named event_name is uploaded with the properties "paramString":"value", "paramNumber":123, and "paramBoolean":true

6. Preset properties of auto-tracked events​

The following preset properties are specific to each auto-tracked event

  • Preset properties of the APP start event (ta_app_start)
Property nameDisplay nameProperty typeDescription

#resume_from_background

Resumed from background

Boolean

Indicates whether the APP was opened or woken from the background. true means it was woken from the background, and false means it was opened directly
#start_reason

Launch reason

Text

The content is a JSON string. When the APP is opened through a URL or an intent, the URL content and the data in the intent are recorded automatically. Example: {url:"thinkingdata://","data":{}}

#background_duration

Background duration

Number

The time the app spent in the background between two start events,

in seconds

  • Preset properties of the APP end event (ta_app_end)
Property nameDisplay nameProperty typeDescription
#durationEvent durationNumericThe duration of this APP visit (from start to end), in seconds
  • Preset properties of the APP view page event (ta_app_view)
Property nameDisplay nameProperty typeDescription
#title

Page Title

TextThe title of the Activity of the current page, whose value is the value of the title property of the Activity
#screen_namePage nameTextThe package name.class name of the Activity of the current page
#urlPage URLTextThe URL of the current page. Call getScreenUrl to set the URL
#referrerReferrer URLTextThe URL of the page before the jump. That page must call getScreenUrl to set the URL
  • Preset properties of the APP control click event (ta_app_click)
Property nameDisplay nameProperty typeDescription
#titlePage TitleTextThe title of the Activity that the control belongs to, whose value is the value of the title property of the Activity
#screen_namePage nameTextThe package name.class name of the Activity that the control belongs to
#element_idElement IDTextThe ID of the control, which uses android:id by default. You can call setViewID to set it
#element_typeElement typeTextThe type of the control
#element_selectorElement selectorTextThe concatenation of the control's viewPath
#element_positionElement positionTextThe position information of the control, uploaded only when the control has a position property
#element_contentElement contentTextThe content on the control
  • Preset properties of the APP crash event (ta_app_crash)
Property nameDisplay nameProperty typeDescription
#app_crashed_reasonException informationTextString. Records the stack trace at the time of the crash

7. Optional plugin​

tip

You need to integrate this plugin only if you want to enable control click events and Fragment page view events.

tip

Starting from version 2.1.0, the plugin is compatible with Gradle 8.0.

Android analytics SDK versionPlugin version
[oldest - 3.0.0)1.2.0
[3.0.0 - 3.1.0]2.1.0
(3.1.0 - latest]2.2.0
buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin2:2.2.0'
    }
}

You can configure the plugin parameters in the project's build.gradle file

apply plugin: 'cn.thinkingdata.android'
android {

}
ThinkingAnalytics {
    debug = true
    exclude = []
    sdk{
        disableAndroidID = false
    }
}

Parameters:

  • debug: whether to enable compile logs. true enables compile logs. The default is false.
  • exclude: excludes classes under a path from scanning. You can set exclude = ['cn.thinkingdata.android','android.support'].
  • useInclude, include: to scan only classes under a path, set useInclude = true and include= ['cn.thinkingdata.android','android.support'].
  • disableAndroidID: whether to disable calling the system API to get the AndroidID. Starting from plugin V2.1.0, you can configure it by setting disableAndroidID = true.

8. Set custom properties​

You can call TDAnalytics.enableAutoTrack(int autoTrackEventType, JSONObject properties) to enable auto-tracking and set custom properties at the same time

JSONObject properties = new JSONObject();
try {
    properties.put("auto_self_define_key", "auto_self_define_value");
} catch (Exception e) {
    e.printStackTrace();
}
TDAnalytics.enableAutoTrack(typeList, properties);

9. Set a callback for auto-tracked events​

By setting a callback, you can get the event type and event properties of the current event when an enabled auto-tracked event occurs, and you can add extra properties to report with the event by setting the return value.

TDAnalytics.enableAutoTrack(TDAnalytics.TDAutoTrackEventType.APP_END | TDAnalytics.TDAutoTrackEventType.APP_START, new TDAnalytics.TDAutoTrackEventHandler() {
    @Override
    public JSONObject getPropertiesWithEventType(int eventType, JSONObject properties) {
        try {
            return new JSONObject("{\"keykey\":\"value1111\"}");
        } catch (JSONException e) {
            e.printStackTrace();
            return null;
        }
    }
});
Was this page helpful?
On this page