README-CN.md

ViewTracker-Android

📖 English Documentation | 📖 中文文档

• 0 概述
  • 0.1 功能特性
  • 0.2 设计原则
  • 0.3 整体架构
  • 0.4 流程图
• 1 生命周期
  • 1.1 系统属性
  • 1.2 View属性
• 2 采集规范
  • 2.1 点击事件规范
  • 2.2 曝光事件规范
• 3 开发接入
  • 3.1 依赖配置
  • 3.2 应用启动时初始化配置
    • 3.2.1 启动初始化(必选)
    • 3.2.2 数据提交方式注入(可选)
  • 3.3 Tag绑定
    • 3.3.1 点击&曝光Tag绑定(必选)
    • 3.3.2 附加信息绑定(可选)
    • 3.3.3 页面公共信息绑定(可选)
    • 3.3.4 运行时信息设置方式（可选）
• 4 性能测试
  • 4.1 性能测试目标
  • 4.2 性能测试环境
  • 4.3 性能测试结果
• 5 开发作者
• 6 许可证
• 7 微信交流群

0 概述

ViewTracker是用于自动化的采集用户UI交互过程中的点击和曝光事件，基于view事件代理及过滤的数据采集库。2016年3月份开始在天猫APP生产环境使用。

0.1 功能特性

• 支持Android & iOS（iOS SDK github 仓库）平台。
• 支持采集点击事件、曝光事件。
• 支持采集页面公共信息。
• 支持多个场景：列表滑动，列表自动滚动，页面内Window切换，Tab页切换，进入下一个页面，应用前后台切换。
• 支持扩展：数据提交、曝光规则自定义(时间阈值和宽高阈值)、采样率定义等。

0.2 设计原则

• KISS原则（Keep It Simple, Stupid）：避免代码复杂化，类名、包名等都语义化，可读性好。
• SRP（单一责任原则）：某块代码功能，明确执行单一任务，如Click与Expourse区分。
• OCP（开闭原则）：最大化支持用户扩展开发，如可以替换数据提交的IDataCommit接口实现；提供广播的receiver入口，支持业务运行时的配置更新。

0.3 整体架构

0.4 流程图

1 生命周期

1.1 系统属性

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

1.2 View属性

• View accessibilityDelegate

2 采集规范

数据采集与后续的数据分析统计息息相关，不同事件的采集规范的约定至关重要。

2.1 点击事件规范

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

2.2 曝光事件规范

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

3 开发接入

3.1 依赖配置

使用gradle:

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

3.2 应用启动时初始化配置

3.2.1 启动初始化(必选)

在应用启动时，调用如下代码：

/**
 * SDK的初始化
 *
 * @param mContext              全局的application
 * @param mTrackerOpen          是否开启无痕点击埋点
 * @param mTrackerExposureOpen  是否开启无痕曝光埋点
 * @param printLog              是否输出调试log
 */
TrackerManager.getInstance().init(mContext, mTrackerOpen, mTrackerExposureOpen, printLog);

3.2.2 数据提交方式注入(可选)

外部注入提交方式，实现IDataCommit接口

Class DataCommit implments IDataCommit {
    ...
    // 你的自定义实现
    ...
}
TrackerManager.getInstance().setCommit(new DataCommit());

注意：

在生产环境使用，应该是定制实现IDataCommit该接口，采集的日志数据才能上传保存到你的服务器端。

3.3 Tag绑定

业务方对于需要采集行为的view上绑定tag，分为以下几种场景。

3.3.1 点击&曝光Tag绑定(必选)

对于需要埋点的view，仅需要绑定view埋点名称。

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

3.3.2 附加信息绑定(可选)

需要埋点的view还可以绑定附加扩展信息。

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

3.3.3 页面公共信息绑定(可选)

• 如果需要同一页面中的所有view上报都需要带上的信息，可以这样绑定（如果需要）。

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 运行时信息设置方式（可选）

服务端配置无痕点击JSON配置格式如下：

{
    "masterSwitch": true, // 是否打开无痕点击事件上报
    "sampling":100 // 点击采样率
}

服务端配置无痕曝光JSON配置格式如下：

{
    "masterSwitch": true, // 是否打开曝光事件上报
    "timeThreshold": 100, // view曝光时长阈值
    "dimThreshold": 0.8, // view曝光宽高阈值
    "exposureSampling": 100, // 曝光采样率
    "batchOpen":false // 是否打开批量上报，即页面离开时，所有view上报一次曝光总时长
}

应用接收到服务端配置后，发送广播，SDK内部可以接收到，动态修改配置。

JSONObject config = new JSONObject();

// 获取服务端无痕点击配置
...
JSONObject exposureConfig = new JSONObject();

// 获取服务端无痕曝光配置
...
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 性能测试

由于每一个本地页面都attach了一个TrackerFrameLayout，在UI主线程的事件处理方法中有曝光时间的计算操作，可能会对页面流畅度有一定影响，所以需要进行性能测试。

4.1 性能测试目标

帧率，监测使用viewtracker采集和原始代码提交埋点方式是否FPS有差别。

4.2 性能测试环境

• 手机型号：小米2
• 系统版本：Android 5.0
• APP版本：天猫Android 5.32.0
• 页面：首页

4.3 性能测试结果

类目	未使用ViewTracker	使用ViewTracker
测试次数	20	20
MAX_FPS	60	63
MIN_FPS	50	47
AVG_FPS	54.81	53.90

测试数据来看，使用该无痕采集方式与传统代买提交方式FPS上无明显影响。

5 开发作者

• @意海 lizhiyonghust <at> gmail <dot> com
• @蒙戈 lmaz <at> 163 <at> com
• @元休

6 许可证

Viewtracker遵循Apache License 2.0协议，查看更多协议信息。

7 微信交流群

• 微信群二维码容易过期，可在微信中搜索Sunshine07de。