add guide doc

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