# Automatic Event Tracking
Android SDK Automatic Event Tracking events including installation,open,close and etc.
# 1. Introduction
TE provides Apis for automatic data tracking. You can select the data to be tracked based on your needs.
Currently, the following types of events can be tracked automatically:
- Install: behavior of APP installation
- Open APP: including activiting APP and resuming APP from the background
- Close APP: including disabling the APP and calling in the background while tracking the duration of the enabling process
- View Page:The user views the screen in the APP (
Activity/Fragment
) - Click:The user clicks on the UI element in the APP
- Crash:Record crash information when the APP crashes
See below for more details on how to start tracking these events.
# 2. Enable Auto-Tracking
You can call enableAutoTrack
to enable the auto-tracking function:
List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL); //APP install event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START); //APP enable event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END); //APP disable event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_VIEW_SCREEN); //APP view screen event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CLICK); //APP click view event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CRASH); //APP crash event
//enable autotrack event
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).enableAutoTrack(eventTypeList);
::: Tips
If you need to track Clicks event or Fragment Views, please integrate auto-tracking plugin.
:::
# Instructions
# 3.1 Installation Events
APP install event would record the installation of the APP and be reported when the APP is being activated. The event is triggered when the APP is activated for the first time after installation. APP upgrade would not trigger an installation event. If the user reinstalls the app after uninstalling it, the installing event will be triggered again.
- Event name: ta_app_install
# 3.2 Active Events
APP started event would be triggered when the user enables the APP or resumes the APP from the background. A detailed description of the start event is as follows:
- Event name: ta_app_start
- Preset property:
#resume_from_background
, Boolean type, indicating whether the APP is enabled by the user or resumed from the background. If the value is true, it means the APP is resumed from the background; if the value is false, it means the APP is enabled by the user directly. - It should be noted that SDK no longer allows the start events triggered by enabling the APP silently . To change the settings, you can 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 Inactive Events
APP end event would be triggered when the user disables the APP or moves the APP to the background. Detailed description of the end event is as follows:
- Event name: ta_app_end
- Preset property:
#duration
, numeric type, indicating the duration of each APP (unit: second).
# 3.4 View Page Events
APP view screen event would be triggered when the user views the screen (Activity
). Detailed event introduction is as follows:
- Event name: ta_app_view
- Preset property:
#screen_name
, string type, package name, and category name of Activity
#title
, string type, title of Activity
, value: the value of title
property of Activity
Other properties could be added to view screen events to expand their analysis value. Methods for defining the properties of view screen events are as follows
# 3.4.1 View Page Events of Auto-Tracking Fragment
As for the Fragment of android.support.v4.app.Fragment
, the following method could be used to track view screen events automatically:
After SDK is initialized, call the following method to enable the auto-tracking function of Fragment
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).trackFragmentAppViewScreen();
As for the Fragment of android.app.Fragment
, the following method could be used to track view screen events automatically:
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).trackViewScreen(targetFragment);
targetFragment
can be replaced by the Fragment that requires uploading of the view screen event
# 3.4.2 Define The Properties of View Page Events
As for the view page events of Activity
, properties could be added by implementing the interface ScreenAutoTracker
. URL information and other self-defined properties could be added for view page events through the following two methods:
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 returned value of <code>getScreenUrl</code>would be used as the URL Schema of the <code>Activity</code>. When the view event of the page is triggered, preset property <code>#url</code> will be added. Meanwhile, SDK will fetch the URL Schema of the page before redirection. If it succeeds, it will be added to the preset property <code>#referrer</code> as the forward address.
The returned value of <code>getTrackProperties</code> is the self-defined property of the view event of the screen, and would join the view event of the screen automatically
As for the view screen event of <code>Fragment</code>, we provide two ways to add properties
- Add attributes by
@ThinkingDataFragmentTitle
@ThinkingDataFragmentTitle(title = "myFragment")
public class ListViewFragment extends BaseFragment {
// your fragment implementations
}
- Implements
ScreenAutoTracker
@Override
public JSONObject getTrackProperties() {
try {
JSONObject properties = new JSONObject();
properties.put("#title", "RecyclerViewFragment");
return properties;
} catch (JSONException e) {
// ignore
}
return null;
}
# 3.5 Clicked Events
App view click event would be triggered when the user clicks the element
- Event name: ta_app_click
- Preset property:
#screen_name
, character string type, package.class
of the Activity
to which the view belongs
#title
, character string type, the title of the Activity
to which the view belongs, value: the value of title
property of Activity
#element_content
, character string type, the content of the view
#element_type
, character string type, type of the view
#element_id
,character string type, the ID of the view, android:id
should be used by default
#element_position
,character string type, uploaded when the view is in its position
#element_selector
,character string type, the splicing of the viewPath
of the view
# 3.5.1 Define ViewID
The viewID should be android:id
by default. If such property is unavailable, or the user wants to define the view ID, the following method could be used to cover #element_id
property
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).setViewID(view,viewID);
As for Dialog
, the following method could be applied:
//android.app.Dialog
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).setViewID(view,viewID);
or
//android.support.v7.app.AlertDialog
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).setViewID(view,viewID);
Parameter view
is the view that needs a view ID, while parameter viewID
is the preset view ID. When the clicking event of the view is being uploaded, the value of #element_id
will be the value uploaded.
# 3.5.2 Define The Properties of Clicked Events
You can apply the following method to add self-defined properties for Clicking a certain view.
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).setViewProperties(view,properties);
Parameter view is the view that needs self-defined properties, while parameter properties
(type:JSONObject
) are the present self-defined properties, which will be added when the click event of the view is uploaded.
Besides, as for ExpandableListView
, ListView
and GridView
, you can also add self-defined properties when clicking a certain item by realizing interface with an Adapter.
ExpandableListView
should implementsThinkingExpandableListViewItemTrackProperties
interface
public interface ThinkingExpandableListViewItemTrackProperties {
/**
* Add properties when clicking items at groupPosition and childPosition
* @param groupPosition
* @param childPosition
* @return
* @throws JSONException
*/
JSONObject getThinkingChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;
/**
* Add properties when clicking items at groupPosition
* @param groupPosition
* @return
* @throws JSONException
*/
JSONObject getThinkingGroupItemTrackProperties(int groupPosition) throws JSONException;
}
ListView
andGridView
should implementThinkingAdapterViewItemTrackProperties
interface
public interface ThinkingAdapterViewItemTrackProperties {
/**
* Add properties when clicking items in the position
* @param position
* @return
* @throws JSONException
*/
JSONObject getThinkingItemTrackProperties(int position) throws JSONException;
}
# 3.5.3 Add Activity information for Clicked Event of AlertDialog
As for the clicked event of AlertDialog (android.app.AlertDialog and android.support.v7.app.AlertDialog
), the following methods could be applied to bind with the screen (Activity
) concerned. In this case, the #screen_name
and #title
property of the screen would be added to the click event.
- Please apply the following method to call
dialog.show()
and display dialog:
dialog.setOwnerActivity(targetActivity);
- Please apply the following method to call
builder.show()
and display dialog:
builder.show().setOwnerActivity(activity);
# 3.5.4 Add Clicked Events by Adding Annotation @ThinkingDataTrackViewOnClick
If you use the calling method of adding a clicked event for viewing through android:onclick
, you can add annotation @ThinkingDataTrackViewOnClick
. When the calling method is being implemented, SDK will upload the view click event.
@ThinkingDataTrackViewOnClick
public void buttonOnClick(View v){}
If the buttonOnClick
method is being called, the clicked event will be uploaded
# 3.6 Crash Events
When an unexpected crash occurs in the APP, an APP crash event would be reported
- Event name: ta_app_crash
- Preset property:
#app_crashed_reason
, character string type, record the stack trace upon crash
# 4.Ignore Auto-Tracking Event
You can ignore the auto-tracking event of activity or view by the following means
# 4.1 View Page Events
As for certain screens (Activity
), if you do not want to transmit auto-tracking events (including view screen event and view click event), you can ignore them by the following means:
//ignore a single screen
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivity(MainActivity.class);
//ignore multiple screens
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivities(classList);
You can also add annotation @ThinkingDataIgnoreTrackAppViewScreen
before Activity
or Fragment
to ignore the view screen event of a certain Activity
or Fragment
//ignore the view screen event of TestActivity
@ThinkingDataIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
...
}
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
before Activity
to ignore the view screen event of a certain Activity
as well as the view click event under the screen
//ignore the view screen event ofTestActivity as well as the view click event under the screen
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
...
}
# 4.2 Clicked Events
- You can apply the following method to ignore the click event of a certain view type
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).ignoreViewType(ignoredClass);
ignoredClass
is the type of view that needs to be ignored. For example,Dialog
andCheckbox
, etc.
- You can apply the following method to ignore the click event of a certain element (view)
ThinkingAnalyticsSDK.sharedInstance(this, TE_APP_ID).ignoreView(targetView);
targetView
is the View to be ignored
# Tracking Events By Annotation
If you need to monitor the call time of a certain method, or an event needs to be uploaded once a method is called, you can use annotation @ThinkingDataTrackEvent
to set the event to be uploaded rapidly. It should be noted that variables could not be uploaded for properties. Therefore, only simple events could be uploaded.
//use annotation
@ThinkingDataTrackEvent(eventName = "event_name", properties = "{\"paramString\":\"value\",\"paramNumber\":123,\"paramBoolean\":true}")
public void fun(){}
In this case, if method fun
is called, an even named event_name
and such properties as "paramString":"value"
, "paramNumber":123
and "paramBoolean":true
will be uploaded
# 6.Preset Properties of Auto-Tracking Events
The following preset properties are the properties set specially for each auto-tracking event
- Preset properties of APP start event (ta_app_start)
Property name | Display name | Property type | Instruction |
---|---|---|---|
#resume_from_background | Resume from the background or not | Bool | Indicating whether the APP is enabled by the user or resumed from the background. If the value is true, it means the APP is resumed from the background; if the value is false, it means the APP is enabled by the user directly. |
#start_reason | APP enable source | Text | The content is JSON character string; when the APP is enabled by url or intent method, the url content and the data in intent would be recorded automatically. For the sample, please refer to: {url:"thinkingdata://","data":{}} |
#background_duration | Background duration | Numeric value | Record the background duration of the APP in the time interval between two start events (Unit: second) |
Preset properties of APP end event (ta_app_end)
Preset properties of APP view screen event (ta_app_view)
Preset properties of APP view click event
Preset properties of APP crash event (ta_app_crash)
# 7. Optional Plugin
::: Tips
This plugin should only be integrated when you need to enable the view click event and Fragment view screen.
:::
apply plugin: 'cn.thinkingdata.android'
buildscript {
repositories {
google()
jcenter()
}
dependencies {
classpath 'cn.thinkingdata.android:android-gradle-plugin2:1.0.5'
}
}
Relevant parameters of the plugin could be configured in the build.gradle file of the project
apply plugin: 'cn.thinkingdata.android'
android {
}
ThinkingAnalytics {
debug = true
disableJar = true
exclude = []
excludeSensitive = []
}
If you want to open the compile log, you can set debug as true, whose default value is false.
If you want to forbid a class in jars, you can set disableJar = true,
whose default value is false
If you do not want to scan the class under a certain route, you can set
exclude = ['cn.thinkingdata.android','android.support']
Code isolation of sensitive properties (e.g., Android ID) can be configured by setting excludeSensitive = ['AndroidID']