ViewTracker-Android

:book: English Documentation | :book: Chinese Documentation

• 0 Abstract
  • 0.1 Functions
  • 0.2 Design Principles
  • 0.3 Basic Architecture
  • 0.4 Flow Chart
• 1 Life-Cycle
  • 1.1 System Properties
  • 1.2 View Properties
• 2 Collection Specification
  • 2.1 The Specification Of Click Event
  • 2.2 The Specification Of Exposure Event
• 3 Developer Guide
  • 3.1 Dependency configuration
  • 3.2 Initialization
    • 3.2.1 Startup Initialization(required)
    • 3.2.2 Data Submission(optional)
  • 3.3 Tag Binding
    • 3.3.1 The Tag Of Click & Exposure(required)
    • 3.3.2 The Tag Of Extended Information(optional)
    • 3.3.3 The Tag Of Page Common Information(optional)
    • 3.3.4 The Tag Of Run-time Information(optional)
• 4 Performance Testing
  • 4.1 The Goal Of Testing
  • 4.2 The Environment Of Testing
  • 4.3 The Results Of Testing
• 5 Authors
• 6 License
• 7 WeChat Group

0 Abstract

ViewTracker is used to collect the mobile client of click and exposure event log automatically. It has been used in tmall App production environment from March 2016.

0.1 Functions

• Support Android & iOS(the github repo of iOS SDK).
• Support click & exposure events collection.
• Support the common information of page.
• Support multiple scenes, e.g. slides, automatic scrolling, window switch, tab switch, page jump, front and back switch.
• Support extension, e.g. data submission, customization for the exposure rules, sampling rate, etc.

0.2 Design Principles

• Keep It Simple, Stupid(KISS) Principle: Avoid code complexity, class name, package name etc have good readability.
• Single Responsibility Principle(SRP): A piece of code function that explicitly performs a single task, such as click and exposure.
• Open/Closed Principle(OCP): Maximize extensibility for user, such as you can replace the implementation of IDataCommit interface data submission; providing receiver of dynamic config, you can integrate with your own config system.

0.3 Basic Architecture

0.4 Flow Chart

1 Life-Cycle

1.1 System Properties

• Application onCreate
• FrameLayout onLayout/onFling/disPatchWindowFocusChanged/dispatchVisibilityChanged
• GestureDetector onGestureListener

1.2 View Properties

• View accessibilityDelegate

2 Collection Specification

Data collection is closely related to data analysis statistics, the collection Specification of different events is critical.

2.1 The Specification Of Click Event

• EventId: 2101
• ControlName: button-1
• args: key1=value,key2=value

2.2 The Specification Of Exposure Event

• EventId: 2201
• ControlName: button-1
• exposureTime: 500
• args: exposureIndex=1,key1=value

3 Developer Guide

3.1 Dependency configuration

To add a dependency using Gradle:

compile('com.tmall.android:viewtracker:1.0.0@aar')

3.2 Initialization

3.2.1 Startup Initialization(required)

When the application starts, call the following:

/**
 * SDK initilization
 *
 * @param mContext              global context
 * @param mTrackerOpen          click event switch,yes means open
 * @param mTrackerExposureOpen  exposure event switch,yes means open
 * @param printLog              debug log switch,yes means open
 */
TrackerManager.getInstance().init(mContext, mTrackerOpen, mTrackerExposureOpen, printLog);

3.2.2 Data Submission(optional)

Implement the IDataCommit interface to set up data submission.

Class DataCommit implments IDataCommit {
	...
	// your implementation here
	...
}
TrackerManager.getInstance().setCommit(new DataCommit());

CAUTION:

You should implement the interface IDataCommit in production environment, because the collected log data need be saved on your own server-side.

3.3 Tag Binding

Tag needs to be bound to the view that needs to be collected. Look at the following situations.

3.3.1 The Tag Of Click & Exposure(required)

String viewName = "button-1";
view.setTag(TrackerConstants.VIEW_TAG_UNIQUE_NAME, viewName);

3.3.2 The Tag Of Extended Information(optional)

The extended information is bound to the view

HashMap<String, String> args = new HashMap<String, String>();
args.put(key, value);
...
view.setTag(TrackerConstants.VIEW_TAG_PARAM, args);

3.3.3 The Tag Of Page Common Information(optional)

All the views of the page are required to be reported,you can look at the following code.

HashMap<String, String> args = new HashMap<String, String>();
args.put(key, value);
...
getWindow().getDecorView().setTag(TrackerConstants.DECOR_VIEW_TAG_COMMON_INFO, args);

3.3.4 The Tag Of Run-time Information(optional)

The server-side click event configuration JSON format is as follows:

{
    "masterSwitch": true, // Click event switch
    "sampling":100 // Click event sampling rate
}

The server-side exposure event configuration JSON format is as follows:

{
    "masterSwitch": true, // exposure event switch
    "timeThreshold": 100, // Valid exposure time threshold
    "dimThreshold": 0.8, // Valid exposure area threshold
    "exposureSampling": 100, // Exposure event sampling rate
    "batchOpen":false //Batch report switch
}

After receiving the server configuration, the application sends the broadcast, and the SDK can receive and dynamically modify the configuration.

//get click config from server-side
JSONObject config = new JSONObject();

// get exposure config from server-side
...
JSONObject exposureConfig = new JSONObject();

// send broadcast
...
Intent intent = new Intent(ConfigReceiver.ACTION_CONFIG_CHANGED);
intent.putExtra(ConfigReceiver.VIEWTRACKER_CONFIG_KEY, config.toString());
intent.putExtra(ConfigReceiver.VIEWTRACKER_EXPOSURE_CONFIG_KEY, exposureConfig.toString());
context.sendBroadcast(intent);

4 Performance Testing

As each page has attached a TrackerFrameLayout, in the UI main thread of the event processing methods have exposure time calculation operation, may have a certain impact on the page fluency, so the need for performance testing.

4.1 The Goal Of Testing

The test the buried two ways of uses the viewtracker collection and the original code to submit for the FPS effect.

4.2 The Environment Of Testing

• Phone Model: xiaomi2
• System Version: Android 5.0
• App: Tmall Android
• App Version: 5.32.0
• Page: HomePage

4.3 The Results Of Testing

Result: ViewTrackerhas no significant effect on FPS.

5 Authors

• @yihai lizhiyonghust <at> gmail <dot> com
• @mengge lmaz <at> 163 <dot> com
• @yuanxiu

6 License

ViewTracker is available under the Apache License 2.0. See the LICENSE file for more info.

7 WeChat Group

Because the QR code of WeChat Group is valid for a short period , you can join us by search Sunshine07de in WeChat.