SDK / TraceSDK

Browse Code »

Commit c249b9af01093ea3136e114f47bdd6ebe2bea2ec

Authored by 赵康 2014-11-20 19:33:08 +0800

1 parent a91e0251b9

Exists in master

add guide doc

Showing 1 changed file with 161 additions and 0 deletions Inline Diff

doc/integerate guide.md

doc/integerate guide.md

Diff comments View file @ c249b9a

File was created	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
	162