SDK / TraceSDK

Blame view

doc/integerate guide.md 7.5 KB
edit raw normal view history
c249b9af0   赵康   add guide doc 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
  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);