MobclickAgent——友盟用户分析工具

Android 统计分析 SDK使用指南

• 1.建立App，下载SDK
• 2.实现基本的使用
• 3.使用错误报告
• 4.使用自定义事件
• 5.使用分发渠道分析
• 6.使用应用程序更新提醒
• 7.使用用户反馈收集
• 8.设置数据发送策略
• 9.使用在线配置功能

1.建立App，下载SDK Top

登录你的帐号后，看到友盟的管理后台，点击"+添加新应用"，进入新应用信息填写的页面。在新应用信息填写中，请尽量填写真实的信息。App建立成功后，可以获得该App的AppKey，以及最新的开发指南和SDK文件。可在这里下载SDK，包含开发文档,demo程序和jar包。

*Tips 
您可以通过友盟统计分析平台的特性节省重复建立App的时间。如果您要对App不同的发布渠道进行统计，不需要创建新App （请查看【使用分发渠道分析】），通过分发渠道分析，您可以更方便的对比数据。

 

2.实现基本的使用 Top

• 导入Analytics_Android_SDK_3.2.1.jar（简称SDK）下载地址：点击打开链接

下载最新版sdk的zip包，解压将其中的Analytics_Android_SDK_3.2.1.jar释放到本地目录，Eclipse用户右键您的工程根目录，选择Properties -> Java    Build Path     -> Libraries， 然后点击Add External JARs... 选择指向       Analytics_Android_SDK_3.2.1.jar   的路径，点击OK，即导入成功。 

• 配置AndroidManifest.xml
  1. 添加应用程序的Appkey(必须), 需要先添加应用程序获得Appkey，获得后写到AndroidManifest.xml的meta-data里。（注意：不要改变字符串'UMENG_APPKEY'）
  2. 添加权限android.permission.INTERNET(必须), 向我们的服务器发送用户分析数据。
  3. 添加权限android.permission.READ_PHONE_STATE(必须), 这个权限仅为了获取用户手机的IMEI，用来唯一的标识用户。(如果您的应用会运行在无法读取IMEI的平板上，我们会将mac地址作为用户的唯一标识，请添加权限： android.permission.ACCESS_WIFI_STATE )
  4. android.permission.ACCESS_NETWORK_STATE (可选),检测网络状态，友盟SDK 1.6版本新增权限。
  5. android.permission.READ_LOGS (可选), 如果您想获得客户端crash的报告, 需要添加这个权限。具体见【使用错误报告】
  6. android.permission.WRITE_EXTERNAL_STORAGE (可选), 如果您使用了友盟自动更新提醒功能，需添加这个权限，为了将更新的APK临时存在SD卡里。
  7. 将应用程序的Appkey (需要先添加应用程序获得Appkey) 写到AndroidManifest.xml的meta-data里。（注意：不要改变'UMENG_APPKEY'）

此处为添加部分

< manifest ……>
< application ……>
    ……
< activity ……/>
< meta-data android:value = "YOUR_APP_KEY" android:name = "UMENG_APPKEY" ></ meta-data >
</ application >
< uses-sdk android:minSdkVersion = "4" ></ uses-sdk >
< uses-permission android:name = "android.permission.ACCESS_NETWORK_STATE" ></ uses-permission >
< uses-permission android:name = "android.permission.INTERNET" ></ uses-permission >
< uses-permission android:name = "android.permission.READ_PHONE_STATE" ></ uses-permission >
< uses-permission android:name = "android.permission.READ_LOGS" ></ uses-permission >
</ manifest >

• 添加代码
  • 添加引用: import com.mobclick.android.MobclickAgent
  • 注册 Activity: 在每个Activity的onResume方法中调用 MobclickAgent.onResume(Context), 传入的参数为当前context的引用，这个方法将会自动地从AndroidManifest.xml文件里读取Appkey。 这里请不要将全局的application context传入。

    public void onResume() {
        super .onResume();
        MobclickAgent.onResume( this );
    }

  • 在每个Activity的onPause方法中调用MobclickAgent.onPause(Context), 只需传入一个参数当前activity的context.

    public void onPause() {
        super .onPause();
        MobclickAgent.onPause( this );
    }

    确保在所有的activity中都调用 MobclickAgent.onResume() 和MobclickAgent.onPause()方法，这两个调用将不会阻塞应用程序的主线程，也不会影响应用程序的性能。注意如果您的Activity之间有继承或者控制关系请不要同时在父和子Activity中重复添加onPause和onResume方法，否则会造成重复统计(eg.使用TabHost、TabActivity、ActivityGroup时)。一个应用程序在多个activity之间连续切换时，将会被视为同一个session(启动)。 
    当用户两次使用之间间隔超过30秒时，将被认为是两个的独立的session(启动)，例如用户回到home，或进入其他程序，经过一段时间后再返回之前的应用。 在V3.1.1.1以上版本中我们提供了新的接口来自定义这个时间间隔，您只要调用：MobclickAgent.setSessionContinueMillis(long)传入适当的参数，就可以控制session重新启动时间，注意参数是以毫秒为单位的。 例如，如果您认为在60秒之内返回应用可视为同一次启动，超过60秒返回当前应用可视为一次新的启动，那么请写成MobclickAgent.setSessionContinueMillis(60000)。

 

• 测试
  • 确认所需的权限都已经添加：INTERNET, READ_PHONE_STATE, (READ_LOGS, WRITE_EXTERNAL_STORAGE)
  • 确认APPKEY已经正确的写入Androidmanifest.xml
  • 确认所有的Activity中都调用了onResume和onPause方法
  • 确认测试手机(或者模拟器)已成功连入网络
  • 启动应用程序，几分钟之后您应该已经可以看到相应的报表.
  • 如果几分钟后报表中仍然没有收到数据，请与我们的技术支持联系 QQ 800083942 或者邮件到[email protected]我们会尽快回复您的报表.

 

3.使用错误报告   Top

友盟统计分析工具，还可以帮助您捕捉用户在使用应用程序过程中出现的异常退出(FC), 并在应用程序下次启动时将错误报告发送给服务器。错误报告包含应用程序版本，操作系统版本和设备型号以及程序出现异常时的Stacktrace，这些数据将帮助您修正应用程序的Bug。我们提供两种方式发送 错误报告，一种是我们自动捕获的错误信息，另外一种是开发者自己传递的错误信息
前者，您需要在AndroidManifest.xml里面添加权限android.permission.READ_LOGS，并且在程序的Main Activity (应用程序入口)的onCreate方法里调用MobclickAgent.onError(Context):

public void onCreate(Bundle savedinstanceState) {
    super .onCreate(savedInstanceState);
    MobclickAgent.onError( this );
    ...
}

后者需要开发者调用 MobclickAgent.reportError(Context context,String error) 在第二个参数中传入，自己扑捉的错误信息。

您可以在我的产品页面，开发者工具-错误分析标签中，查看错误报告。

 

4.使用自定义事件 Top

除了基本统计分析功能外，我们还支持您自定义的事件分析，例如您可以统计游戏中通过不同关卡的人数，广告的点击次数或者视频被播放的次数等等。 使用自定义事件功能请先在网站应用管理后台(设置->编辑自定义事件)中添加相应的自定义事件后，服务器才会对相应的自定义事件请求进行处理。 
这里我们将提供几个简单而通用的接口：

• 简单事件

在您希望发送事件报告的代码段，调用如下方法就可以向服务器发送事件记录

MobclickAgent.onEvent(Context context, String event_id);

统计event_id对应事件的发生次数，变化趋势，例如广告点击，短信数量等等。参数context为当前context的引用。event_id为当前统计的事件ID，注意event_id中不要加空格或其他 的转义字符

比如，在口袋微博应用程序里一条微博被转发定义为事件"Reply"。那么在点击转发的函数里调用 MobclickAgent.onEvent(this, "Reply") 通知服务器一个转发的事件。

Reply事件分析图表示例

 

• 多标签事件

MobclickAgent.onEvent(Context context, String event_id, String  label);

除了能够统计event_id所对应事件的发生次数，变化趋势外，还能统计事件中具体标签所占的比例。label为当前标签，同样这里的event_id字符串中也不能有空格。
比如，在口袋微博程序中，我们定义了一个发布微博的多标签事件"Publish"，对应的发布内容有"Text"（发布文本）,"Pic0"（发小图）,"Pic1"（发中图），"Pic2"(发大图),来对应不同的发布内容，这样我们不仅可以记录Publish事件的点击数量还可以看到不同内容对应的比例。 
多标签事件分析图表示例 

 

• 事件累计

在应用程序中某些自定义事件可能会被频繁触发，例如用户点击某个按钮。开发者可以在程序中维护一个计数器，这样某个事件被多次触发但只需要生成一个消息，这个消息中包括该事件被触发的次数。为了支持这个功能，这里我们简单重载了之前的两个接口：

MobclickAgent.onEvent(Context context, String event_id, int acc);
MobclickAgent.onEvent(Context context, String event_id, String label, int acc)

参数acc是对应事件 （和对应标签）被触发的次数。

 

5.使用分发渠道分析 Top

有时需要统计应用程序的分发渠道，例如有多少用户来从联想乐园下载了您的应用,又有多少用户通过Google android market下载到您的应用程序。您只需要在AndroidManifest.xml里添加meta-data，并将 value属性修改为对应的发布渠道名。

< application ……>
    < activity ……/>
    < meta-data android:value = "Channel ID" android:name = "UMENG_CHANNEL" />
</ application >

当然，这需要您在不同渠道发布应用程序时，重新编译打包。 
注意

• 不要改变'UMENG_CHANNEL'，修改'Channel ID'为您的渠道名称，注意不能是纯数字(eg.value="AndroidMarket")。
• 每台设备只记录第一次统计到的渠道，您如果在测试的时候发现渠道统计到的设备数量不增加，很可能是因为您用同一个设备修改过渠道号。您换一台设备测试即可。

6.使用应用程序更新提醒  Top

这个功能将帮助您把新版应用程序推送给用户，您只需要:

• 将zip包中layout文件夹下的umeng_analyse_download_notification.xml和values、values-en文件夹下的umeng_analyse_strings.xml复制到对应的文件夹下，此XML文件的作用是绘制状态栏里的下载进度条和多语言支持。
• 在应用程序的入口Activity里的OnCreate() 方法中调用 
  

 

public void onCreate(Bundle  savedInstanceState) {
    super .onCreate(savedInstanceState);
    MobclickAgent.update( this );
}

• 每次更新应用程序，您只需要修改VersionCode，把应用程序的apk文件上传到友盟。MobclickAgent.update方法会判断是否有新版应用程序，如果发现可更新的应用程序安装包，会提示用户是否更新。用户选择更新后，安装包会在后台下载自动安装更新。（按照version code来检测是否需要更新） 
  此功能需要添加权限 android.permission.WRITE_EXTERNAL_STORAGE，考虑到用户流程的限制，目前我们默认在Wi-Fi接入情况下才进行自动提醒。如需要在其他网络环境下进行更新自动提醒，则请添加以下代码：

   

  MobclickAgent.setUpdateOnlyWifi( false );

• 同时，我们提供了一个判断下载状态的接口MobclickAgent.isDownloadingAPK() 返回boolean 类型的值，true表示正在下载。

• 如果程序想自己处理更新可以按如下步骤，设置updateAutoPopup= false，我们将禁止主动弹框，实现更新监听接口，处理更新事件：

   

  MobclickAgent.update( this );
  MobclickAgent.updateAutoPopup= false ;
  MobclickAgent.setUpdateListener( new UmengUpdateListener(){
  
  @Override
  public void onUpdateReturned( int arg) {
      switch (arg){
      case 0 :                 //has update
          MobclickAgent.showUpdateDialog(DemoActivity. this );
          Log.i(TAG, "show dialog" );
          break ;
      case 1 :                 //has no update
          Toast.makeText(getParent(), "has no update" , Toast.LENGTH_SHORT).show();
          break ;
      case 2 :                 //none wifi
          Toast.makeText(getParent(), "has no update" , Toast.LENGTH_SHORT).show();
          break ;
      case 3 :                 //time out
          Toast.makeText(getParent(), "time out" , Toast.LENGTH_SHORT).show();
          break ;
      }
  }
  
  });

• 按渠道更新功能: 需要开发者在网站上按照渠道添加对应的更新包，渠道更新的规则是： SDK检测本地安装的软件对应的渠道，然后连接服务器检测更新，如果服务器上有对应渠道的更新包 则选择此更新包并返回提示，如果服务器上没有对应渠道的更新包但有默认的更新包，则选择默认的 更新包并返回提示，如果服务器上没有默认的更新包，但是有其他渠道的更新包，将不会有更新提醒。 
  
• 按天时间间隔更新功能: 通过对update（Context）函数的简单重载，我们提供了一个按时间间隔更新的接口update（Content, long），实现按一定的时间间隔进行更新，比如实现按天更新，只要传作如下调用：update(context, 1000*60*60*24),注意传入的参数，是以毫秒为单位的。这样在下次更新的时候，我们会先检查上次的更新时间，如果间隔超出了设定的值，我们才会再次提示更新。

 

7.使用用户反馈收集  Top

来体验独立的友盟反馈组件吧！它会给您 提供更多的可定制功能。

除了可以通过统计报表，自定义事件等方式了解到用户的使用情况之外，友盟可以帮助开发者收集到最直观的用户反馈。集成用户反馈模块，您只需要:

• 将zip包里的资源文件(layout、values、values-en、drawable)复制到res对应的文件夹下,您可以更改资源但是请不要更改文件名和资源ID。 并在<application>标签中添加新的activity :

< activity android:name = "com.feedback.ui.SendFeedback" android:windowSoftInputMode = "adjustResize" ></ activity >
< activity android:name = "com.feedback.ui.FeedbackConversations" ></ activity >
< activity android:name = "com.feedback.ui.FeedbackConversation" android:configChanges = "keyboard" ></ activity >

• 代码中启用Feedback模块，调用下面函数进入反馈界面：

UMFeedbackService.openUmengFeedbackSDK( this );

• 当开发者回复用户反馈后，如果需要提醒用户，请在应用程序的入口Activity的OnCreate()方法中下添加以下代码：

UMFeedbackService.enableNewReplyNotification( this , NotificationType.AlertDialog);

方法第一个参数类型为：Context，第二个参数为枚举类型，可选值为NotificationType.AlertDialog 或NotificationType.NotificationBar，分别对应两种不同的提示方式： AlertDialog 以 AlertDialog方式提醒用户，NotificationBar 则使用NotificationBar 方式提醒用户。

若调用该接口，反馈模块将在你程序启动后于后台检查是否有新的来自开发者的回复，若有，我们将提醒用户，若无，则不会打扰用户。

你也可以选择不调用该接口，这样我们会在用户进入反馈界面后，再去检查是否存在新的回复。

• 代码示例：

public void onCreate(Bundle savedInstanceState) {
super .onCreate(savedInstanceState);
UMFeedbackService.enableNewReplyNotification( this , 0 );
}

public boolean onCreateOptionsMenu(Menu menu) {
    //一般可以在OptionsMenu中添加一个Item,用于作为反馈界面的入口
menu.add( 0 , 0 , 0 , "feedback" );
...
return true ;
}

public boolean onOptionsItemSelected(MenuItem item) {
switch (item.getItemId()) {
       case 0 :
         // 调用反馈提供的接口，进入反馈界面
UMFeedbackService.openUmengFeedbackSDK( this );
    return true ;
       default :
      ...
 }
 }

• 下面是用户反馈界面的默认样式，您也可以通过修改资源文件来调整样式，不过需要注意的是，不要修改任何元素的ID和文件名.

8.设置数据发送策略 Top

• 启动时发送（推荐使用）

应用程序每次只会在启动时会向服务器发送一次消息，在应用程序过程中产生的所有消息(包括自定义事件和本次使用时长)都会在下次启动时候发送。 如果应用程序启动时处在不联网状态，那么消息将会缓存在本地，下次再尝试发送。 发送策略默认为启动时发送。

• 实时发送

应用程序产生每条消息(包括启动信息，自定义消息，退出消息)时都会立即发送到服务器。

• 设置每日单次发送

设置每日单次发送后，当日第二次及之后的启动将不再发送数据，未发送的数据将缓存在手机，等待次日（或他日）发送。

注：由于不同应用的用户使用行为不同，数据发送会有相应的延迟。

• 设置发送模式

新版本的SDK支持在线动态配置发送策略，您需要在onCreate（）函数中调用MobclickAgent.updateOnlineConfig(this);方法，这样我们就可以在程序启动的时候，联网检测动态配置的发送策略了。详细配置见下面的9.使用在线配置功能。

旧版本SDK（2.3以前版本）发送模式设置需要在onCreate（）函数中调用MobclickAgent.setReportPolicy(int policy)，一旦应用发布就不能再更改,我们推荐使用最新版本的SDK。如果您需要更灵活的发送模式， 请发邮件至[email protected]，我们会尽快回复您。 

9.使用在线配置功能 Top

这个功能目前可以帮你在网站上动态配置两种类型的参数：

• 数据发送策略
• 自定义key-value型的键值对

在程序的入口Activity的OnCreate()方法中调用

public void onCreate(Bundle savedInstanceState) {
  super .onCreate(savedInstanceState);
  MobclickAgent.updateOnlineConfig( this );
}

这样程序启动的时候，我们将联网检测您的在线配置，并将这些信息保存在本地，等待下此启动的时候，我们将按照保存的配置来设定发送策略，您可以通过下面的函数读取您的自定义参数：

String MobclickAgent.getConfigParams(Context c, String key);

参数为 Context 和 在网站上编辑好的key， 返回值是对应的 value 如果没有读到相应的value将返回空字符串("").

同时，我们提供了在线参数回调接口，注意此接口只在在线参数有变化的时候才会回调，实现此接接口：

MobclickAgent.updateOnlineConfig( this );
MobclickAgent.setOnlineConfigureListener( new UmengOnlineConfigureListener(){
      @Override
      public void onDataReceived(JSONObject data) {
      }
});

在没有取到在线配置的发送策略的情况下，会使用默认的发送策略，通过下面函数设置（如果不设置的话，我们默认为启动时发送）

MobclickAgent.setDefaultReportPolicy( this , ReportPolicy.BATCH_AT_LAUNCH);

在线参数设置界面在 开发工具->参数配置 如下图：

数据发送策略设置界面在 统计分析->设置->发送策略 如下图