Mobithink App Tracking SDK
2014-11

开发者接入指南 1.0.0
最后修订：2014-11-20

一、 综述
1.  适用范围
Mobithink App Tracking SDK(以下简称SDK)为移动应用提供数据统计分析服务，通过在应用中加入数
据SDK，来在Mobithink提供的网站中查阅应用的相关数据。
该SDK适用于 Android 1.6（API Level 4）及以上的设备。
2.  统计标准
数据系统中的基本数据单元依据以下标准定义：
Ø  新增用户
Mobithink数据系统中的“用户”指用户的一台唯一设备。
Ø  用户的一次使用
指用户从打开应用的界面至离开界面的完整过程。如用户在离开界面后10秒
内重新回到应用中，将被认为是上次使用被打扰后的延续，记为一次完整使用。
Ø  页面
指Android应用的每个Activity。
Ø  自定义事件
指用户在应用中进行了特定的操作或达成了特定的条件。例如：用户点击了广
告栏、用户进行付费等。
自定义事件用于收集任意您期望跟踪的数据。   

二、 接入数据系统
1.  为应用申请OfferID
向Mobithink索取，用于唯一标识您的一款应用。
2.  向工程中导入追踪SDK
下载数据统计SDK后解压至本地目录，将其中的TraceSDK.jar 导入
至您的工程中；
在Eclipse中（其他开发工具参阅其自带说明）右键点击工程根目录→选择
Properties --> Java Build Path --> Libraries → 点击Add External JARs…找
到本地目录下的TraceSDK.jar 文件，点击 打开按钮 即导入成功。
3.  配置ANDROIDMANIFEST.XML文件
应用需要的权限   用途 
INTERNET
允许程序联网和发送统计数据的权限。
ACCESS_NETWORK_STATE   允许应用检测网络连接状态，在网络异常状态
下避免数据发送，节省流量和电量。
READ_PHONE_STATE   允许应用以只读的方式访问手机设备的信息，
通过获取的信息来唯一标识用户。
ACCESS_WIFI_STATE  获取设备的MAC地址，同样用来标识唯一用
户。 
WRITE_EXTERNAL_STORAGE
用于保存设备信息，以及记录日志。


示例代码：
<?xml version="1.0" encoding="utf-8"?>
<manifest ......>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<application ......>
<activity ......>
......
</activity>
......

</application>
</manifest>

4.  添加SDK初始化代码

在应用启动的时候（比如在启动应用的activity的onCreate方法中）调用以下方法：
TraceAgent.active(Activity, offerId);
5.  添加必须的调用方法
使用数据统计系统需要至少添加以下调用方法，这些调用用于准确跟踪用户每次的
应用使用，是准确统计启动、活跃、留存数据的基础：
Ø  在应用的每个Activity的onResume方法里调用
TraceAgent.onResume(Activity context)，传入的参数为当前Activity实例，
用于跟踪用户使用中的打开应用和页面跳转的数据。
@Override
protect void onResume() {
super.onResume();
TraceAgent.onResume(this);
}

Ø  在应用的每个Activity中的onPause方法里调用TraceAgent.onPause(Activity 
context)，传入的参数为当前的Activity实例，用于跟踪用户离开页面和退出
应用的数据。
@Override
protect void onPause() {
super.onPause();
TraceAgent.onPause(this);
}
n  注意1：确保在每个activity中都调用了以上方法，否则可能造成应用的
使用时长、页面访问时长数据错误。
n  注意2：对有继承关系的Activity，只需要对上层Activity基类添加调用
即可，否则可能会重复计量，造成数据错误。
n  注意3：对于会内嵌其他Activity的ActivityGroup(比如TabActivity)，
建议不要在ActivityGroup里添加调用，而是在所有内嵌的Activity里
添加。
n  注意4：如果应用只支持API Level 14以上的设备，可只在应用的入口
Activity添加调用.

3.  使用自定义事件
用法说明
自定义事件用于统计任何您期望去跟踪的数据，如：点击某功能按钮、填写某个输
入框、触发了某个广告等；同时，自定义事件还支持添加一些描述性的属性参数，
使用多对Key-Value的方式来进行发送（非必须使用），用来对事件发生时的状
况做详尽分析。 

Ø  格式：32个字符以内的中文、英文、数字、下划线，注意eventId中不要加
空格或其他的转义字符。
Ø  最多支持100个不同的Event ID。
如果您要跟踪更多的事件，我们提供了Label参数的用法，可 以 给 多 个 要 跟 踪
的同类型或类似的事件使用相同的Event ID，通过给他们分配不同Label来
达到区分跟踪多个事件的目的。这可理解为Event ID成为了多个事件的目录，
EventID+Label形成了一个具体事件。请对事件做好分类，这也对您管理和
查阅事件数据有利。
调用方法
Ø  在应用程序要跟踪的事件处加入下面格式的代码，也就成功的添加了一个简单
事件到您的应用程序中了：
TraceAgent.onEvent(Context ctx, String EVENT_ID);
Ø  跟踪多个同类型事件，无需定义多个Event ID，可以使用Event ID做为目录
名，而使用Label标签来区分这些事件，可按照下面格式添加代码：
TraceAgent.onEvent(Context ctx, String EVENT_ID, String EVENT_LABEL);
Ø  为事件添加详尽的描述信息，可以更有效的对事件触发的条件和场景做分析，
可按照下面格式添加代码：
TraceAgent.onEvent(Context ctx, String EVENT_ID, Map<String, Object> kv);
注: 此Map的Value仅支持字符串（String）类型，其
他类型会自动调用toString()方法转换为String进行处理。每一次事件数据支
持10对不同参数传入。在Value使用String格式时，报表中将给出事件发
生时每种value出现的频次

 


示例1：
跟踪某电商应用中首页的5个不同推广位置的点击次数，并收集宣传品的品类、
促销价格等信息：
// 可定义eventId=点击首页推荐位；event_LABEL=具体的位置编号
@Override
public void onClick(View v) {
Map<String, Object> kv = new HashMap<String, Object>();
kv.put("商品类型", "休闲食品");
kv.put("价格","5～10元" );
TraceAgent.onEvent(DemoActivity.this, "点击首页推荐位", kv);
}
•  注1：这 里 追 踪 的 事 件属于同类型，使用了Label标签的用法。以相同Event 
ID来作为统一名称，Label来确定不同位置。这样查阅Event ID数据即
可了解全部推广位总量点击数据，展开Label可查阅具体某位置数据。
•  注2：在value取值较离散情况下（如示例中收集的促销价格信息），不
要直接填充具体数值，而应划分区间后传入（如9.9元，可定义5～10元
的价格区间，传入5～10元），否则value不同取值很可能超过平台最
大数目限制，离散数据也对分析人员阅览数据造成影响。
示例2：
在一款休闲游戏中记录玩家在各关卡中的失败数据，并收集玩家具体信息。
// 可定义eventId=战斗失败
Map<String, Object> kv = new HashMap<String, Object>();
kv.put("等级", “20-30”); //级别区间，注意是字符串
kv.put("关卡类别", “星空神域”); //关卡的大类别
kv.put("关卡号", “第5关”); //关卡具体编号
kv.put("失败原因", “主动退出”); //失败原因
kv.put("该局分数", “10000～12000”); //玩家该局所打分数
TCAgent.onEvent(DemoActivity.this, "战斗失败", kv);