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

  自定义事件用于统计任何您期望去跟踪的数据，如：点击某功能按钮、填写某个输
  入框、触发了某个广告等；同时，自定义事件还支持添加一些描述性的属性参数，
  使用多对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);