SDK / TraceSDK

integerate guide.md 8.42 KB

Mobithink App Tracking SDK
2014-11

开发者接入指南 1.0.0
最后修订：2014-12-02

一、 综述

  1. 适用范围
    Mobithink App Tracking SDK(以下简称SDK)为移动应用提供数据统计分析服务，通过在应用中加入数 据SDK，来在Mobithink提供的网站中查阅应用的相关数据。 该SDK适用于 Android 2.2（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);
}

    注意1：确保在每个activity中都调用了以上方法，否则可能造成应用的使用时长、页面访问时长数据错误。
    注意2：对有继承关系的Activity，只需要对上层Activity基类添加调用即可，否则可能会重复计量，造成数据错误。
    注意3：对于会内嵌其他Activity的ActivityGroup(比如TabActivity)，建议不要在ActivityGroup里添加调用，而是在所有内嵌的Activity里添加。
    注意4：如果应用只支持API Level 14以上的设备，可只在应用的入口Activity添加调用.

  6. 使用事件追踪
    Ø 追踪用户升级,需要用户等级作为参数

    TraceAgent.onUpgrade(Context ctx,String level);

    Ø 追踪用户注册

    TraceAgent.onRegister(Context ctx);

    Ø 追踪支付事件,需要货币和金额作为参数

    TraceAgent.onPurchase(Context ctx,String currency,float amount);

  7. 使用自定义事件
    用法说明
    自定义事件用于统计任何您期望去跟踪的数据，如：点击某功能按钮、填写某个输 入框、触发了某个广告等；同时，自定义事件还支持添加一些描述性的属性参数， 使用多对Key-Value的方式来进行发送（非必须使用），用来对事件发生时的状 况做详尽分析。
    Ø 格式：32个字符以内的中文、英文、数字、下划线，注意eventId中不要加 空格或其他的转义字符。
    Ø 最多支持100个不同的Event ID。
    如果您要跟踪更多的事件，我们提供了Label参数的用法，可 以 给 多 个 要 跟 踪 的同类型或类似的事件使用相同的Event ID，通过给他们分配不同Label来 达到区分跟踪多个事件的目的。这可理解为Event ID成为了多个事件的目录， EventID+Label形成了一个具体事件。请对事件做好分类，这也对您管理和查阅事件数据有利。
    Ø 属性参数中Key不可以使用保留关键字,保留关键字如下:
    def,purchase,register,upgrade
    调用方法
    Ø 在应用程序要跟踪的事件处加入下面格式的代码，也就成功的添加了一个简单 事件到您的应用程序中了： 

    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);