From c249b9af01093ea3136e114f47bdd6ebe2bea2ec Mon Sep 17 00:00:00 2001 From: King Date: Thu, 20 Nov 2014 19:33:08 +0800 Subject: [PATCH] add guide doc --- doc/integerate guide.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 doc/integerate guide.md diff --git a/doc/integerate guide.md b/doc/integerate guide.md new file mode 100644 index 0000000..49d3dbc --- /dev/null +++ b/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 +用于保存设备信息，以及记录日志。 + + +示例代码： + + + + + + + + + +...... + +...... + + + + +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 kv); +注: 此Map的Value仅支持字符串（String）类型，其 +他类型会自动调用toString()方法转换为String进行处理。每一次事件数据支 +持10对不同参数传入。在Value使用String格式时，报表中将给出事件发 +生时每种value出现的频次 + + + + +示例1： +跟踪某电商应用中首页的5个不同推广位置的点击次数，并收集宣传品的品类、 +促销价格等信息： +// 可定义eventId=点击首页推荐位；event_LABEL=具体的位置编号 +@Override +public void onClick(View v) { +Map kv = new HashMap(); +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 kv = new HashMap(); +kv.put("等级", “20-30”); //级别区间，注意是字符串 +kv.put("关卡类别", “星空神域”); //关卡的大类别 +kv.put("关卡号", “第5关”); //关卡具体编号 +kv.put("失败原因", “主动退出”); //失败原因 +kv.put("该局分数", “10000～12000”); //玩家该局所打分数 +TCAgent.onEvent(DemoActivity.this, "战斗失败", kv); + -- 2.0.0