SDK / TraceSDK

Download as
Browse Code »

Commit 518491f414026101e0df9197bd9fc8c0cd4e4f2d

Authored by 赵康
2 parents a820d907c5 6e6ed75a77
Exists in master

Merge branch 'master' of http://git.letsgame.mobi/document/tracesdk

Showing 1 changed file Inline Diff

doc/integerate guide.md
Diff comments   View file @ 518491f
1
2 Mobithink App Tracking SDK 1 Mobithink App Tracking SDK
3 2014-11 2 2014-11
4 3
5 开发者接入指南 1.0.0 4 开发者接入指南 1.0.0
6 最后修订：2014-11-20 5 最后修订：2014-12-02
7 6
8 # 一、 综述 7 # 一、 综述
9 1. 适用范围 8 1. 适用范围
10 Mobithink App Tracking SDK(以下简称SDK)为移动应用提供数据统计分析服务，通过在应用中加入数 9 Mobithink App Tracking SDK(以下简称SDK)为移动应用提供数据统计分析服务，通过在应用中加入数
11 据SDK，来在Mobithink提供的网站中查阅应用的相关数据。 10 据SDK，来在Mobithink提供的网站中查阅应用的相关数据。
12 该SDK适用于 Android 1.6（API Level 4）及以上的设备。 11 该SDK适用于 Android 2.2（API Level 4）及以上的设备。
13 2. 统计标准 12 2. 统计标准
14 数据系统中的基本数据单元依据以下标准定义： 13 数据系统中的基本数据单元依据以下标准定义：
15 Ø 新增用户 14 Ø 新增用户
16 Mobithink数据系统中的“用户”指用户的一台唯一设备。 15 Mobithink数据系统中的“用户”指用户的一台唯一设备。
17 Ø 用户的一次使用 16 Ø 用户的一次使用
18 指用户从打开应用的界面至离开界面的完整过程。如用户在离开界面后10秒 17 指用户从打开应用的界面至离开界面的完整过程。如用户在离开界面后10秒
19 内重新回到应用中，将被认为是上次使用被打扰后的延续，记为一次完整使用。 18 内重新回到应用中，将被认为是上次使用被打扰后的延续，记为一次完整使用。
20 Ø 页面 19 Ø 页面
21 指Android应用的每个Activity。 20 指Android应用的每个Activity。
22 Ø 自定义事件 21 Ø 自定义事件
23 指用户在应用中进行了特定的操作或达成了特定的条件。例如：用户点击了广 22 指用户在应用中进行了特定的操作或达成了特定的条件。例如：用户点击了广
24 告栏、用户进行付费等。 23 告栏、用户进行付费等。
25 自定义事件用于收集任意您期望跟踪的数据。 24 自定义事件用于收集任意您期望跟踪的数据。
26 25
27 # 二、 接入数据系统 26 # 二、 接入数据系统
28 1. 为应用申请OfferID 27 1. 为应用申请OfferID
29 向Mobithink索取，用于唯一标识您的一款应用。 28 向Mobithink索取，用于唯一标识您的一款应用。
30 2. 向工程中导入追踪SDK 29 2. 向工程中导入追踪SDK
31 下载数据统计SDK后解压至本地目录，将其中的TraceSDK.jar 导入 30 下载数据统计SDK后解压至本地目录，将其中的TraceSDK.jar 导入
32 至您的工程中； 31 至您的工程中；
33 在Eclipse中（其他开发工具参阅其自带说明）右键点击工程根目录→选择 32 在Eclipse中（其他开发工具参阅其自带说明）右键点击工程根目录→选择
34 Properties --> Java Build Path --> Libraries → 点击Add External JARs…找 33 Properties --> Java Build Path --> Libraries → 点击Add External JARs…找
35 到本地目录下的TraceSDK.jar 文件，点击 打开按钮 即导入成功。 34 到本地目录下的TraceSDK.jar 文件，点击 打开按钮 即导入成功。
36 3. 配置ANDROIDMANIFEST.XML文件 35 3. 配置ANDROIDMANIFEST.XML文件
37 应用需要的权限 用途 36 应用需要的权限 用途
38 INTERNET 允许程序联网和发送统计数据的权限。 37 INTERNET 允许程序联网和发送统计数据的权限。
39 ACCESS_NETWORK_STATE 允许应用检测网络连接状态，在网络异常状态下避免数据发送，节省流量和电量。 38 ACCESS_NETWORK_STATE 允许应用检测网络连接状态，在网络异常状态下避免数据发送，节省流量和电量。
40 READ_PHONE_STATE 允许应用以只读的方式访问手机设备的信息，通过获取的信息来唯一标识用户。 39 READ_PHONE_STATE 允许应用以只读的方式访问手机设备的信息，通过获取的信息来唯一标识用户。
41 ACCESS_WIFI_STATE 获取设备的MAC地址，同样用来标识唯一用户。 40 ACCESS_WIFI_STATE 获取设备的MAC地址，同样用来标识唯一用户。
42 WRITE_EXTERNAL_STORAGE 用于保存设备信息，以及记录日志。 41 WRITE_EXTERNAL_STORAGE 用于保存设备信息，以及记录日志。
43 42
44 示例代码： 43 示例代码：
45 44
46 <?xml version="1.0" encoding="utf-8"?> 45 <?xml version="1.0" encoding="utf-8"?>
47 <manifest ......> 46 <manifest ......>
48 <uses-permission android:name="android.permission.INTERNET"/> 47 <uses-permission android:name="android.permission.INTERNET"/>
49 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> 48 <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
50 <uses-permission android:name="android.permission.READ_PHONE_STATE" /> 49 <uses-permission android:name="android.permission.READ_PHONE_STATE" />
51 <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /> 50 <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
52 51
53 <application ......> 52 <application ......>
54 <activity ......> 53 <activity ......>
55 ...... 54 ......
56 </activity> 55 </activity>
57 ...... 56 ......
58 57
59 </application> 58 </application>
60 </manifest> 59 </manifest>
61 60
62 4. 添加SDK初始化代码 61 4. 添加SDK初始化代码
63 在应用启动的时候（比如在启动应用的activity的onCreate方法中）调用以下方法： 62 在应用启动的时候（比如在启动应用的activity的onCreate方法中）调用以下方法：
64 63
65 TraceAgent.active(Activity, offerId); 64 TraceAgent.active(Activity, offerId);
66 5. 添加必须的调用方法 65 5. 添加必须的调用方法
67 使用数据统计系统需要至少添加以下调用方法，这些调用用于准确跟踪用户每次的应用使用，是准确统计启动、活跃、留存数据的基础： 66 使用数据统计系统需要至少添加以下调用方法，这些调用用于准确跟踪用户每次的应用使用，是准确统计启动、活跃、留存数据的基础：
68 Ø 在应用的每个Activity的onResume方法里调用TraceAgent.onResume(Activity context),传入的参数为当前Activity实例，用于跟踪用户使用中的打开应用和页面跳转的数据。 67 Ø 在应用的每个Activity的onResume方法里调用TraceAgent.onResume(Activity context),传入的参数为当前Activity实例，用于跟踪用户使用中的打开应用和页面跳转的数据。
69 68
70 @Override 69 @Override
71 protect void onResume() { 70 protect void onResume() {
72 super.onResume(); 71 super.onResume();
73 TraceAgent.onResume(this); 72 TraceAgent.onResume(this);
74 } 73 }
75 Ø 在应用的每个Activity中的onPause方法里调用TraceAgent.onPause(Activity context)，传入的参数为当前的Activity实例，用于跟踪用户离开页面和退出应用的数据。 74 Ø 在应用的每个Activity中的onPause方法里调用TraceAgent.onPause(Activity context)，传入的参数为当前的Activity实例，用于跟踪用户离开页面和退出应用的数据。
76 75
77 @Override 76 @Override
78 protect void onPause() { 77 protect void onPause() {
79 super.onPause(); 78 super.onPause();
80 TraceAgent.onPause(this); 79 TraceAgent.onPause(this);
81 } 80 }
82 81
83 注意1：确保在每个activity中都调用了以上方法，否则可能造成应用的使用时长、页面访问时长数据错误。 82 注意1：确保在每个activity中都调用了以上方法，否则可能造成应用的使用时长、页面访问时长数据错误。
84 注意2：对有继承关系的Activity，只需要对上层Activity基类添加调用即可，否则可能会重复计量，造成数据错误。 83 注意2：对有继承关系的Activity，只需要对上层Activity基类添加调用即可，否则可能会重复计量，造成数据错误。
85 注意3：对于会内嵌其他Activity的ActivityGroup(比如TabActivity)，建议不要在ActivityGroup里添加调用，而是在所有内嵌的Activity里添加。 84 注意3：对于会内嵌其他Activity的ActivityGroup(比如TabActivity)，建议不要在ActivityGroup里添加调用，而是在所有内嵌的Activity里添加。
86 注意4：如果应用只支持API Level 14以上的设备，可只在应用的入口Activity添加调用. 85 注意4：如果应用只支持API Level 14以上的设备，可只在应用的入口Activity添加调用.
87 86
88 6. 使用自定义事件 87 6. 使用事件追踪
88 Ø 追踪用户升级,需要用户等级作为参数
89
90 TraceAgent.onUpgrade(Context ctx,String level);
91
92 Ø 追踪用户注册
93
94 TraceAgent.onRegister(Context ctx);
95
96 Ø 追踪支付事件,需要货币和金额作为参数
97
98 TraceAgent.onPurchase(Context ctx,String currency,float amount);
99
100 7. 使用自定义事件
89 用法说明 101 用法说明
90 自定义事件用于统计任何您期望去跟踪的数据，如：点击某功能按钮、填写某个输 102 自定义事件用于统计任何您期望去跟踪的数据，如：点击某功能按钮、填写某个输
91 入框、触发了某个广告等；同时，自定义事件还支持添加一些描述性的属性参数， 103 入框、触发了某个广告等；同时，自定义事件还支持添加一些描述性的属性参数，
92 使用多对Key-Value的方式来进行发送（非必须使用），用来对事件发生时的状 104 使用多对Key-Value的方式来进行发送（非必须使用），用来对事件发生时的状
93 况做详尽分析。 105 况做详尽分析。
94 Ø 格式：32个字符以内的中文、英文、数字、下划线，注意eventId中不要加 106 Ø 格式：32个字符以内的中文、英文、数字、下划线，注意eventId中不要加
95 空格或其他的转义字符。 107 空格或其他的转义字符。
96 Ø 最多支持100个不同的Event ID。 108 Ø 最多支持100个不同的Event ID。
97 如果您要跟踪更多的事件，我们提供了Label参数的用法，可 以 给 多 个 要 跟 踪 109 如果您要跟踪更多的事件，我们提供了Label参数的用法，可 以 给 多 个 要 跟 踪
98 的同类型或类似的事件使用相同的Event ID，通过给他们分配不同Label来 110 的同类型或类似的事件使用相同的Event ID，通过给他们分配不同Label来
99 达到区分跟踪多个事件的目的。这可理解为Event ID成为了多个事件的目录， 111 达到区分跟踪多个事件的目的。这可理解为Event ID成为了多个事件的目录，
100 EventID+Label形成了一个具体事件。请对事件做好分类，这也对您管理和 112 EventID+Label形成了一个具体事件。请对事件做好分类，这也对您管理和查阅事件数据有利。
101 113 Ø 属性参数中Key不可以使用保留关键字,保留关键字如下:
102 查阅事件数据有利。 114 def,purchase,register,upgrade
103 调用方法 115 调用方法
104 Ø 在应用程序要跟踪的事件处加入下面格式的代码，也就成功的添加了一个简单 116 Ø 在应用程序要跟踪的事件处加入下面格式的代码，也就成功的添加了一个简单
105 事件到您的应用程序中了： 117 事件到您的应用程序中了：
106 118
107 TraceAgent.onEvent(Context ctx, String EVENT_ID); 119 TraceAgent.onEvent(Context ctx, String EVENT_ID);
108 Ø 跟踪多个同类型事件，无需定义多个Event ID，可以使用Event ID做为目录 120 Ø 跟踪多个同类型事件，无需定义多个Event ID，可以使用Event ID做为目录
109 名，而使用Label标签来区分这些事件，可按照下面格式添加代码： 121 名，而使用Label标签来区分这些事件，可按照下面格式添加代码：
110 122
111 TraceAgent.onEvent(Context ctx, String EVENT_ID, String EVENT_LABEL); 123 TraceAgent.onEvent(Context ctx, String EVENT_ID, String EVENT_LABEL);
112 Ø 为事件添加详尽的描述信息，可以更有效的对事件触发的条件和场景做分析， 124 Ø 为事件添加详尽的描述信息，可以更有效的对事件触发的条件和场景做分析，
113 可按照下面格式添加代码： 125 可按照下面格式添加代码：
114 126
115 TraceAgent.onEvent(Context ctx, String EVENT_ID, Map<String, Object> kv); 127 TraceAgent.onEvent(Context ctx, String EVENT_ID, Map<String, Object> kv);
116 注: 此Map的Value仅支持字符串（String）类型，其 128 注: 此Map的Value仅支持字符串（String）类型，其
117 他类型会自动调用toString()方法转换为String进行处理。每一次事件数据支 129 他类型会自动调用toString()方法转换为String进行处理。每一次事件数据支
118 持10对不同参数传入。在Value使用String格式时，报表中将给出事件发 130 持10对不同参数传入。在Value使用String格式时，报表中将给出事件发
119 生时每种value出现的频次 131 生时每种value出现的频次
120 示例1： 132 示例1：
121 跟踪某电商应用中首页的5个不同推广位置的点击次数，并收集宣传品的品类、 133 跟踪某电商应用中首页的5个不同推广位置的点击次数，并收集宣传品的品类、
122 促销价格等信息： 134 促销价格等信息：
123 // 可定义eventId=点击首页推荐位；event_LABEL=具体的位置编号 135 // 可定义eventId=点击首页推荐位；event_LABEL=具体的位置编号
124 136
125 @Override 137 @Override
126 public void onClick(View v) { 138 public void onClick(View v) {
127 Map<String, Object> kv = new HashMap<String, Object>(); 139 Map<String, Object> kv = new HashMap<String, Object>();
128 kv.put("商品类型", "休闲食品"); 140 kv.put("商品类型", "休闲食品");
129 kv.put("价格","5～10元" ); 141 kv.put("价格","5～10元" );
130 TraceAgent.onEvent(DemoActivity.this, "点击首页推荐位", kv); 142 TraceAgent.onEvent(DemoActivity.this, "点击首页推荐位", kv);
131 } 143 }
132 • 注1：这 里 追 踪 的 事 件属于同类型，使用了Label标签的用法。以相同Event 144 • 注1：这 里 追 踪 的 事 件属于同类型，使用了Label标签的用法。以相同Event
133 ID来作为统一名称，Label来确定不同位置。这样查阅Event ID数据即 145 ID来作为统一名称，Label来确定不同位置。这样查阅Event ID数据即
134 可了解全部推广位总量点击数据，展开Label可查阅具体某位置数据。 146 可了解全部推广位总量点击数据，展开Label可查阅具体某位置数据。
135 • 注2：在value取值较离散情况下（如示例中收集的促销价格信息），不 147 • 注2：在value取值较离散情况下（如示例中收集的促销价格信息），不
136 要直接填充具体数值，而应划分区间后传入（如9.9元，可定义5～10元 148 要直接填充具体数值，而应划分区间后传入（如9.9元，可定义5～10元
137 的价格区间，传入5～10元），否则value不同取值很可能超过平台最 149 的价格区间，传入5～10元），否则value不同取值很可能超过平台最
138 大数目限制，离散数据也对分析人员阅览数据造成影响。 150 大数目限制，离散数据也对分析人员阅览数据造成影响。
139 示例2： 151 示例2：
140 在一款休闲游戏中记录玩家在各关卡中的失败数据，并收集玩家具体信息。 152 在一款休闲游戏中记录玩家在各关卡中的失败数据，并收集玩家具体信息。
141 // 可定义eventId=战斗失败 153 // 可定义eventId=战斗失败
142 154
143 Map<String, Object> kv = new HashMap<String, Object>(); 155 Map<String, Object> kv = new HashMap<String, Object>();
144 kv.put("等级", “20-30”); //级别区间，注意是字符串 156 kv.put("等级", “20-30”); //级别区间，注意是字符串
145 kv.put("关卡类别", “星空神域”); //关卡的大类别 157 kv.put("关卡类别", “星空神域”); //关卡的大类别
146 kv.put("关卡号", “第5关”); //关卡具体编号 158 kv.put("关卡号", “第5关”); //关卡具体编号
147 kv.put("失败原因", “主动退出”); //失败原因 159 kv.put("失败原因", “主动退出”); //失败原因
148 kv.put("该局分数", “10000～12000”); //玩家该局所打分数 160 kv.put("该局分数", “10000～12000”); //玩家该局所打分数