目录
此内容是否有帮助?

# Android SDK Automatic Collection Guide

# I. Introduction to Automatic Collection

The TA system provides an interface for automatic data collection. You can choose the data that needs to be collected automatically according to your business needs.

The currently supported automatic collection event types are:

  1. APP Installation, Logging APP Installed
  2. APP start-up, including opening APP and waking up from the background
  3. APP closure, including closing APP and moving into the background, while collecting startup time
  4. Users browse the page in the APP ( Activity)
  5. User clicks control in APP
  6. Record crash information when APP crashes

Next, we will introduce in detail the collection method of each data.

# II. Turn on Automatic Acquisition

You can use enableAutoTrackto turn on the automatic collection function:

List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();

//APP Installation Event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);

//APP Startup Event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);

//APP Closure Event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);

//APP Browse Page Events
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_VIEW_SCREEN);

//APP Click Control Event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CLICK);

//APP Collapse Event
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CRASH);

//Turn on automatic collection event
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).enableAutoTrack(eventTypeList);

Automatic collection of events can be started according to business needs.

TIP

If you need to collect control click events or Fragment browsing events, you need to integrate the automatic collection plug-in .

To set public event properties or set custom guest IDs, make sure to call setSuperProperties () or identify () before turning on automatic collection.

Code sample:

// Initialise SDK
ThinkingAnalyticsSDK.sharedInstance(this, "TA_APP_ID","TA_SERVER_URL");

// Set Visitor ID
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).identify("123456789ABCabc");

// Set Common Event Properties
try {
    JSONObject superProperties = new JSONObject();
    superProperties.put("Channel","B1");
    ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setSuperProperties(superProperties);
} catch (JSONException e) {
    e.printStackTrace();
}

//After setting visitor ID and public attributes, start automatic collection
List<ThinkingAnalyticsSDK.AutoTrackEventType> eventTypeList = new ArrayList<>();
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_VIEW_SCREEN);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CLICK);
eventTypeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_CRASH);

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).enableAutoTrack(eventTypeList);

# III. Detailed Automated Acquisition Events

# 3.1 APP Installation Event

The app installation event will record the actual installation of the app and report it when the app is started. The event trigger time is the time when the app is started for the first time after installation. The app upgrade will not trigger the installation event, but the installation event will be reported after deletion and re-installation.

  • Event name: ta_app_install

# 3.2 APP Launch Event

The APP startup event will be triggered when the user opens the APP or wakes up the APP from the background. The detailed event description is as follows:

  • Event name: ta_app_start
  • Preset attribute: #resume_from_background, Boolean type, indicating whether the APP is turned on by the user or woken up from the background. The value of true indicates waking up from the background, and false is directly turned on.

# 3.3 APP Shutdown Event

The APP shutdown event will be triggered when the user closes the APP or adjusts the APP to the background. The detailed event is described as follows:

  • Event name: ta_app_end
  • Preset attribute: #duration, numeric, indicating the duration of the APP access (from start to end), in seconds.

# 3.4 APP Browsing Page Events

The APP browsing page event will trigger the browsing page event when the user browses the page ( Activity). The detailed event description is as follows:

  • Event name: ta_app_view
  • Preset properties:
  • #screen_name, string type, the package name of the activity. Class name
  • #title, string type, is the title of the Activity, and the value is the value of the titleattribute of the Activity

Other properties can be added to the page browsing event to extend its analysis value. The following is how to customize the properties of the page browsing event

# 3.4.1 Turn on page browsing events that automatically collect Fragments

For Fragments that android.support.v4.app. Fragment, you can use the following methods to automatically collect page browsing events:

After the SDK initialization is complete, call the following method to start the automatic collection function of Fragment

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).trackFragmentAppViewScreen();

For Fragments that android.app. Fragments, you can invoke the page browsing event yourself by:

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).trackViewScreen(targetFragment);
  • The targetFragmentcan be replaced with a Fragment that needs to upload page browsing events

# 3.4.2 Customize the properties of page browsing events

For Activity's page browsing events, you can add attributes by implementing the interface ScreenAutoTracker. By overwriting the following two methods, you can add page URL information and other custom attributes for page browsing 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 getScreenUrlwill be used as the URL Schema of the Activity. When the browsing event of the page is triggered, the preset attribute #urlwill be added. The value is the URL Schema of the current page. At the same time, the SDK will take the URL Schema of the page before the jump. If it can be taken, it will be added to the preset attribute #referreras the forward address.

The return value of getTrackPropertiesis a custom attribute of the browsing event of the page and will be automatically added to the browsing event of the page

  1. For Fragment's page browsing event, you can

By adding a comment to the Fragmentclass @ThinkingDataFragmentTitle, for example

@ThinkingDataFragmentTitle(title = "myFragment")
public class ListViewFragment extends BaseFragment {
  // your fragment implementations
}

Through Fragmentto implement the ScreenAutoTrackerinterface, add the #titleattribute to the custom attribute

  @Override
  public JSONObject getTrackProperties() {
      try {
          JSONObject properties = new JSONObject();
          properties.put("#title", "RecyclerViewFragment");
          return properties;
      } catch (JSONException e) {
          // ignore
      }
      return null;
  }

# 3.5 App Control Click Event

App control click event will be triggered when the user clicks the control (view)

  • Event name: ta_app_click
  • Preset properties:
  • #screen_name, string type, is the package name of the activitythat the control belongs to. Class name
  • #title, string type, is the title of the Activityto which the control belongs, and the value is the value of the titleproperty of the Activity
  • #element_content, string type, for the content of the control
  • #element_type, string type, is the type of control
  • #element_id, string type, the ID of the control, the default is android: id
  • #element_position, string type, will only upload when the control has position
  • #element_selector, string type, splicing for the viewPathof the control

There are several ways to set more properties to extend the analytic value of click events for a View on a page:

# 3.5.1 Custom Control ID

The default ID of the control is android: id. If the property cannot be fetched, or you want to customize the control ID, you can use the following methods to override the #element_idproperty

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

For Dialog, you can use the following method:

//android.app.Dialog
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

Or

//android.support.v7.app.AlertDialog
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewID(view,viewID);

The parameter viewis the view that needs to set the control ID, and the parameter viewIDis the set control ID. When uploading the click event of the control, the value of #element_idis the incoming value here

# 3.5.2 Custom control click event properties

You can add custom properties to the click event of a control (view) by:

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).setViewProperties(view,properties);

The parameter viewis the view that needs to set custom properties, the parameter properties, the type is JSONObject, and the custom properties that are set. When the click event of the control is uploaded, these properties will be added.

In addition, for ExpandableListView, ListViewand GridView, you can also add custom attributes when clicking on an item by implementing the interface through Adapter.

  • ExpandableListViewneeds to implement the ThinkingExpandableListViewItemTrackPropertiesinterface
public interface ThinkingExpandableListViewItemTrackProperties {
    /**
     * Add when click groupPosition、childPosition, the attribute of item
     * @param groupPosition
     * @param childPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingChildItemTrackProperties(int groupPosition, int childPosition) throws JSONException;

    /**
     * Add when click groupPosition、childPosition, the attribute of item
     * @param groupPosition
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingGroupItemTrackProperties(int groupPosition) throws JSONException;
}
  • ListViewand GridViewneed to implement ThinkingAdapterViewItemTrackPropertiesinterface
public interface ThinkingAdapterViewItemTrackProperties {
    /**
     * Add attribute when clicking item in position
     * @param position
     * @return
     * @throws JSONException
     */
    JSONObject getThinkingItemTrackProperties(int position) throws JSONException;
}

# 3.5.3 Click on AlertDialog to add Activity information

For AlertDialog( android.app. AlertDialogand android.support.v7.app. AlertDialog) click events, you can bind the page ( Activity) by the following methods, and the #screen_nameand #titleattributes of the page will be added in the click event.

  • To display the dialog by using dialog.show (), use the following methods:
dialog.setOwnerActivity(targetActivity);
  • To display the dialog by using builder.show (), use the following methods:
builder.show().setOwnerActivity(activity);

# 3.5.4 Upload control click events via annotation @ThinkingDataTrackViewOnClick

If you are using the android: onclickcall method to add a click event to the control (view), you can add a comment on the call method @ThinkingDataTrackViewOnClick. When the call method is executed, the SDK will upload the control click event.

@ThinkingDataTrackViewOnClick
public void buttonOnClick(View v){}

If the method buttonOnClickis called, the control click event will be uploaded.

# 3.6 APP Crash Event

An app crash event is reported when the app has an uncaught exception

  • Event name: ta_app_crash
  • Preset attributes:
  • #app_crashed_reason, character type, record the stack trajectory when crashing

# IV. Ignore Automatic Acquisition Events

You can ignore automatic collection events for a page or control by

# 4.1 Ignore page auto-capture events

For some pages ( Activities), if you do not want to transmit automatic collection events (including page browsing and control click events), you can ignore them by the following methods:

//Ignore Single Page
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivity(MainActivity.class);

//Multiple Page Ignorance
List<Class<?>> classList = new ArrayList<>();
classList.add(MainActivity.class);
ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreAutoTrackActivities(classList);

You can also add a comment before Activityor Fragment @ThinkingDataIgnoreTrackAppViewScreen, ignoring a Activityor Fragment's page browsing event.

//Ignore page browsing events for TestActivity
@ThinkingDataIgnoreTrackAppViewScreen
public class TestActivity extends AppCompatActivity {
    ...
}

Add a comment before Activity @ThinkingDataIgnoreTrackAppViewScreenAndAppClick, ignoring an Activitypage browsing event and the control click event under the page.

//忽略 TestActivity 的页面浏览事件与该页面下的控件点击事件
@ThinkingDataIgnoreTrackAppViewScreenAndAppClick
public class TestActivity extends AppCompatActivity {
    ...
}

# 4.2 Ignore click events for a type of control

If you need to ignore click events for a type of control, you can use the following methods to ignore

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreViewType(ignoredClass);
  • IgnredClassis the widget type that needs to be ignored, such as Dialog, Checkbox,etc

# 4.3 Ignore the click event of an element (View)

If you want to ignore the click event of an element (View), you can use the following methods to ignore

ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID).ignoreView(targetView);
  • The targetViewis the View that needs to be ignored

# V. Use Notes to Set Events Quickly

If you need to monitor the number of calls to a method, or if a method needs to upload an event once it is called, you can use annotations @ThinkingDataTrackEventQuickly set the events that need to be uploaded. It should be noted that the property cannot be passed in variables, so it is only suitable for uploading simple events.

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

At this time, if the method funis called, an event named event_namewith the attributes of "paramString": "value", "paramNumber": 123and "paramBoolean": truewill be uploaded.

# VI. Preset Attributes of Automatic Acquisition Events

The following preset attributes are unique to each automatic acquisition event.

  • Preset properties for APP launch event (ta_app_start)
Attribute name
 Chinese name
 Description
#resume_from_background
 Whether to wake up from the background
 Indicates whether the APP is turned on or woken up from the background, the value of true indicates waking up from the background, and false is directly turned on
  • Preset properties for APP shutdown events (ta_app_end)
Attribute name
 Chinese name
 Description
#duration
 Event duration
 Represents the duration of the APP visit (from start to end) in seconds
  • Preset properties for APP browsing page events (ta_app_view)
Attribute name
 Chinese name
 Description
#title
 Page Title
 The title of the
Activity
to which the control belongs, with the value of the
title
property of the
Activity
#screen_name
 Page name
 The package name for the
Activity
to which the control belongs. Class name
#url
 Page address
 The address of the current page, you need to call
getScreenUrl
to set the url
#referrer
 Forward address
 The address of the page before the jump, the page before the jump needs to call
getScreenUrl
to set the url
  • Preset properties for APP control click events (ta_app_click)
Attribute name
 Chinese name
 Description
#title
 Page Title
 The title of the
Activity
to which the control belongs, with the value of the
title
property of the
Activity
#screen_name
 Page name
 The package name for the
Activity
to which the control belongs. Class name
#element_id
 Element ID
 The ID of the control, the default is
android: id
, you can call
setViewID
to set
#element_type
 Element type
 Control type
#element_selector
 Element selector
 Splicing for the
viewPath
of a control
#element_position
 Element position
 Control's position information, uploaded when the control has a
position
property
#element_content
 Element content
 Content on the control
  • Preset properties for app crash events (ta_app_crash)
Attribute name
 Chinese name
 Description
#app_crashed_reason
 Abnormal information
 Character type to record the stack trajectory when crashing

# VII. Integrated Automatic Acquisition Function Plug-in (optional)

TIP

You need to integrate this plug-in only if you need to turn on control click events and Fragment page browsing events.

apply plugin: 'cn.thinkingdata.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin:2.0.2'
    }
}

If you are using a version of the SDK before 2.0.0, please use the old version of the plugin:

apply plugin: 'com.thinkingdata.analytics.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'com.thinking.analyselibrary.plugin:android-gradle-plugin:1.2.0'
    }
}

If you want to support lambda expressions and solve errors during compilation, you can use the latest version of the plug-in, and the integrated sdk version must not be less than 2.7.6.

apply plugin: 'cn.thinkingdata.android'

buildscript {
    repositories {
        google()
        jcenter()
    }
    dependencies {
        classpath 'cn.thinkingdata.android:android-gradle-plugin2:1.0.0'
    }
}

You can configure plug-in related parameters in the project build.gradle file.

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

}
ThinkingAnalytics {
    debug = true
    disableJar = true
    exclude = []
}

If you want to open the compilation log, you can set debug = true, the default is false

If you want to disable scanning of classes in the jar, you can set disableJar = true, the default is false

If you don't want to scan classes under a path, you can set exclude = ['cn.thinkingdata.android', 'android.support']

# VIII. Set Custom Attributes for Automatic Acquisition Events

You can use enableAutoTrack (List < ThinkingAnalyticsSDK. AutoTrackEventType >, JSONObject)', turn on the automatic collection function, and set custom attributes.

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

You can also call setAutoTrackProperties (List < ThinkingAnalyticsSDK. AutoTrackEventType >, JSONObject)to set or update custom properties

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

# IX. Automatic Acquisition Event Setting Callback

After **V2.7.5 **, you can set the callback to get the event type of the current event and the event attributes carried by the enabled automatic collection event when it occurs, and you can **set the return value **to add additional attributes to the event that need to be reported.

List<ThinkingAnalyticsSDK.AutoTrackEventType> typeList = new ArrayList<>();
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_START);
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_INSTALL);
typeList.add(ThinkingAnalyticsSDK.AutoTrackEventType.APP_END);

mInstance.enableAutoTrack(typeList, new ThinkingAnalyticsSDK.AutoTrackEventListener() {
    @Override
    public JSONObject eventCallback(ThinkingAnalyticsSDK.AutoTrackEventType eventType, JSONObject properties) {
        try {
            return new JSONObject("{\"keykey\":\"value1111\"}");
        } catch (JSONException e) {
            e.printStackTrace();
            return null;
        }
    }
});

← Android SDK Multi-Instance Guide →