友盟+搜索

{{errorMsg}}

标准统计集成文档集成文档

集成准备

获得Appkey

集成【友盟+】SDK之前,您首先需要到 【友盟+】官网注册并且添加新应用,获得Appkey

特别提醒 :我们建议开发者在注册账号时使用企业邮箱,避免使用个人邮箱注册,防止由于个人离职带来的问题,建议使用的账号形式:umeng@企业域名、apps@企业域名、dev@企业域名。

FAQ

Q :应用的安卓版和IOS版能否共用一个appkey

A :不同平台的应用禁止使用相同的Appkey,需要分开注册。

Q :注册应用时,提示应用名称已存在;

A :【友盟+】后台的应用名与实际应用名和包名无关,建议命名为应用名+平台(IOS/Android)。

下载SDK

将下载的SDK zip包解压缩,需要使用如下Jar包:

  • common/umeng-common-1.x.0.jar //统计的基础服务包
  • analytics/umeng-analytics-7.x.0.jar //统计包
  • thirdparties/utdid4xxxx.jar //这个包为包含阿里UTDID服务的补充包,如果您要使用 标签/画像服务,那么请导入本包,部分阿里SDK已经集成了该SDK,如果集成后发现冲突,则可以删除该包

导入SDK

导入SDK有以下三种方法,选择其中一种即可 。

eclipse开发环境SDK集成

将需要的jar包拷贝到本地工程libs子目录下;在Eclipse中右键工程根目录,选择 Properties -> Java Build Path -> Libraries ,然后点击Add External JARs... 选择指向jar的路径,点击OK,即导入成功。(ADT17及以上不需要手动导入)

使用Android Studio导入SDK

Android Studio是谷歌推出了新的Android开发环境,【友盟+】支持AndroidStudio的Gradle配置,如您使用Android Studio开发,请在您的App对应build.gradle文件中加入对统计SDK和Common通用组件库的依赖:

dependencies
{
    compile file(dir:'libs',include:['umeng-analytics-7.x.0.jar'])
    compile file(dir:'libs',include:['umeng-common-1.x.0.jar'])
}

添加SDK在maven中心库的线上依赖

通过在Android Studio工程build.gradle配置脚本中添加maven线上依赖,导入最新版本组件化基础库和统计SDK。

在Gradle依赖中添加:

dependencies {
    compile 'com.umeng.sdk:common:latest.integration'
    compile 'com.umeng.sdk:analytics:latest.integration'
}

如果无法正常集成请添加如下配置:

allprojects {
    repositories {
            mavenCentral()     
    }
}

基本功能集成

场景类型设置接口

场景类型设置接口:

MobclickAgent.setScenarioType(Context context, EScenarioType etype)

etype是官方场景,有如下场景:

EScenarioType.E_UM_NORMAL 普通统计场景类型

EScenarioType.E_UM_GAME 游戏场景类型

UTDID相关

为防止冲突UTDID包单独提供,如果需要请导入UTDID包

配置APPKEY和SecretKey

XML配置appkey

manifest的配置主要包括添加权限,代码示例如下:

<manifest……>
<uses-sdk android:minSdkVersion="8"></uses-sdk>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"></uses-permission>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET"></uses-permission>
<uses-permission android:name="android.permission.READ_PHONE_STATE"></uses-permission>
<application ……>
……
<meta-data android:value="YOUR_APP_KEY" android:name="UMENG_APPKEY"/> 
<meta-data android:value="Channel ID" android:name="UMENG_CHANNEL"/> 
</application>    
</manifest>


权限说明
权限 用途
ACCESS_NETWORK_STATE(必须) 检测联网方式,区分用户设备使用的是2G、3G或是WiFi
READ_PHONE_STATE(必须) 获取用户设备的IMEI,通过IMEI和mac来唯一的标识用户。
ACCESS_WIFI_STATE(必须) 获取用户设备的mac地址,在平板设备上,无法通过imei标示设备,我们会将mac地址作为用户的唯一标识
INTERNET(必须) 允许应用程序联网,以便向我们的服务器端发送数据。

注意: 新版本中即使已经在AndroidManifest.xml中配置appkey和channel值,也需要在App代码中调用初始化接口(如需要使用AndroidManifest.xml中配置好的appkey和channel值,UMConfigure.init调用中appkey和channel参数请置为null):

 UMConfigure.init(Context context, String appkey, String channel, int deviceType, String pushSecret);

或者

 UMConfigure.init(Context context, int deviceType, String pushSecret);

否则影响统计功能。

代码设置APPKEY

在程序Application的onCreate函数中调用初始化接口,设置Appkey/Channel/Push Secret Key。

 UMConfigure.init(Context context, String appkey, String channel, int deviceType, String pushSecret);

或者

 UMConfigure.init(Context context, int deviceType, String pushSecret);

初始化函数说明请点击:初始化及通用接口

设置Secret Key

新增secret Key接口,防止appkey被盗用,secretkey网站申请

MobclickAgent.setSecret(Context context, String secretkey)

Session统计

在每个Activity的onResume方法中调用 MobclickAgent.onResume(Context),

onPause方法中调用 MobclickAgent.onPause(Context)

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


  • 确保在所有的Activity中都调用 MobclickAgent.onResume() 和onPause()方法,这两个调用将不会阻塞应用程序的主线程,也不会影响应用程序的性能。
  • 注意如果您的Activity之间有继承或者控制关系请不要同时在父和子Activity中重复添加nPause和nResume方法,否则会造成重复统计,导致启动次数异常增高。(eg.使用TabHost、TabActivity、ActivityGroup时)。
  • 当应用在后台运行超过30秒(默认)再回到前端,将被认为是两个独立的session(启动),例如用户回到home,或进入其他程序,经过一段时间后再返回之前的应用。可通过接口:setSessionContinueMillis(long interval) 来自定义这个间隔(参数单位为毫秒)。
  • 如果开发者调用kill或者exit之类的方法杀死进程,请务必在此之前调用onKillProcess(Context context)方法,用来保存统计数据。

    session统计的相关问题请参见【友盟+】开发者社区: 启动次数的统计原理单次使用时长的统计原理

至此,基本功能集成已经结束。

非常重要:必须调用 MobclickAgent.onResume() 和MobclickAgent.onPause()方法,才能够保证获取正确的新增用户、活跃用户、启动次数、使用时长等基本数据。

账号的统计

【友盟+】在统计用户时以设备为标准,如果需要统计应用自身的账号(需使用5.6.1及以上版本SDK),请使用以下接口:

public static void onProfileSignIn(String ID) ;
public static void onProfileSignIn(String Provider, String ID) ;


  • ID:用户账号ID,长度小于64字节
  • Provider:账号来源。如果用户通过第三方账号登陆,可以调用此接口进行统计。支持自定义,不能以下划线"_"开头,使用大写字母和数字标识,长度小于32 字节; 如果是上市公司,建议使用股票代码。
public static void onProfileSignOff();

  • 账号登出时需调用此接口,调用之后不再发送账号相关内容。

示例:

//当用户使用自有账号登录时,可以这样统计:
MobclickAgent.onProfileSignIn("userID");
//当用户使用第三方账号(如新浪微博)登录时,可以这样统计:
MobclickAgent.onProfileSignIn("WB","userID");


启动账号统计

集成账号统计功能后,请到我的产品-设置-应用信息,选择启动使用账号统计报表,如下图

如果您集成了新版SDK的账号接口,可以通过启动账号统计开关,来开启账号报表的展现。账号统计报表开关仅作用于报表的展现,不影响数据的计算。您可以根据实际的需要来启动或者暂停该功能。集成此功能的第二天才能在后台报表看见账号的数据。可在下图所示位置查看

页面的统计

页面统计集成正确,才能够获取正确的页面访问路径、访问深度(PV)的数据。

页面访问路径的数据为全量统计。若您希望查看测试数据,请使用 集成测试 ,了解更多集成测试请 点击这里

页面统计的常见问题参见【友盟+】开发者社区: 页面访问路径中你需要了解的知识点页面访问路径常见问题详解

只由Activity构成的应用

如果您已经完成2.3步骤之前的代码添加,那么SDK已默认统计了每个Activity的跳转路径。页面统计不需要再添加其他代码。

包含Activity、Fragment或View的应用

统计应用中包含Fragment的情况比较复杂,首先要明确一些概念。

  1. MobclickAgent.onResume() 和MobclickAgent.onPause() 方法是用来统计应用时长的(也就是Session时长,当然还包括一些其他功能)

  2. MobclickAgent.onPageStart()和MobclickAgent.onPageEnd()方法是用来统计页面跳转的

在仅有Activity的应用中,SDK 自动帮助开发者调用了 2 中的方法,并把Activity 类名作为页面名称统计。但是在包含fragment的程序中我们希望统计更详细的页面,所以需要自己调用方法做更详细的统计。

首先,需要在程序入口处,调用 MobclickAgent.openActivityDurationTrack(false) 禁止默认的页面统计方式,这样将不会再自动统计Activity。

然后需要手动添加以下代码:

  1. 使用 MobclickAgent.onResume 和 MobclickAgent.onPause方法统计时长, 这和基本统计中的情况一样(针对Activity)

  2. 使用 MobclickAgent.onPageStart 和 MobclickAgent.onPageEnd 方法统计页面(针对页面,页面可能是Activity 也可能是Fragment或View)

如果页面是直接由Activity实现的,统计代码大约是这样:

public void onResume() {
    super.onResume();
    MobclickAgent.onPageStart("SplashScreen"); //统计页面(仅有Activity的应用中SDK自动调用,不需要单独写。"SplashScreen"为页面名称,可自定义)
    MobclickAgent.onResume(this);          //统计时长
}
public void onPause() {
    super.onPause();
    MobclickAgent.onPageEnd("SplashScreen"); // (仅有Activity的应用中SDK自动调用,不需要单独写)保证 onPageEnd 在onPause 之前调用,因为 onPause 中会保存信息。"SplashScreen"为页面名称,可自定义
    MobclickAgent.onPause(this);
}


如果页面是使用FragmentActivity + Fragment实现的,需要在 FragmentActivity 中统计时长:

public void onResume() {
    super.onResume();
    MobclickAgent.onResume(this);       //统计时长
}
public void onPause() {
    super.onPause();
    MobclickAgent.onPause(this);
}


并在其包含的 Fragment 中统计页面:

public void onResume() {
    super.onResume();
    MobclickAgent.onPageStart("MainScreen"); //统计页面,"MainScreen"为页面名称,可自定义
}
public void onPause() {
    super.onPause();
    MobclickAgent.onPageEnd("MainScreen"); 
}


注意: 这些方法的调用,需要保证线性不交叉,每个 onResume 都对应一个 onPause ,每个 Start 都有一个 End 配对。这样才能保证每个页面统计的正确。

发送策略

发送策略设定了用户产生的数据发送回【友盟+】服务器的频率。

Android平台的数据发送策略有两种方式:

  1. 启动时发送:新增、活跃、启动次数等数据在APP本次打开时即刻发送,使用时长、自定义事件、错误统计等在使用过程中产生的所有消息数据都在下次启动应用时发送。如果应用程序启动时处在不联网状态,那么消息将会缓存在本地,下次再尝试发送。

  2. 按间隔发送:按特定间隔发送数据,间隔时长介于90秒与1天之间。新增、活跃、启动次数等数据在APP本次打开时即刻发送,使用时长、自定义事件、错误统计等在使用过程中产生的所有数据都按间隔发送,如果应用程序启动时处在不联网状态,那么消息将会缓存在本地,下次再尝试发送。

发送策略设置方法

您可以在后台统计分析->设置->发送策略 页面自定义发送间隔。具体如下图:

点击发送策略之后,可以看到设置页面

注意

(1)在没有获取到在线配置时,默认使用启动时发送的策略。

(2)在打开debug调试模式或者使用集成测试时,不受发送策略控制。

日志加密设置

您可以通过在程序入口处的 Activity 中调用如下代码来设置加密模式

//设置是否对日志信息进行加密, 默认false(不加密). 

UMConfigure.setEncryptEnabled (boolean enable);

  • 如果enable为true,SDK会对日志进行加密。加密模式可以有效防止网络攻击,提高数据安全性。
  • 如果enable为false,SDK将按照非加密的方式来传输日志。
  • 如果您没有设置加密模式,SDK的加密模式为false(不加密)。

代码混淆

如果您的应用使用了混淆, 请添加

-keepclassmembers class * {
   public <init> (org.json.JSONObject);
}


这是由于SDK中的部分代码使用反射来调用构造函数, 如果被混淆掉, 在运行时会提示"NoSuchMethod"错误。 另外,由于SDK需要引用导入工程的资源文件,通过了反射机制得到资源引用文件R.java,但是在开发者通过proguard等混淆/优化工具处理apk时,proguard可能会将R.java删除,如果遇到这个问题,请在proguard配置文件中添加keep命令如:

-keep public class [您的应用包名].R$*{
public static final int *;
}


把[您的应用包名] 替换成您自己的包名,如com.yourcompany.example。如果您使用5.0.0及以上版本的SDK,请添加如下命令:

-keepclassmembers enum * {
    public static **[] values();
    public static ** valueOf(java.lang.String);
}


自定义事件的统计

自定义事件可以实现在应用程序中埋点来统计用户的点击行为。自定义事件目前包括"计数事件"和"计算事件",二者的区别以及详细说明请 点击这里

自定义事件使用中的问题请参见【友盟+】开发者社区: 自定义事件常见问题关于自定义事件的那些事儿

自定义事件字段说明

event id:自定义事件id

key:自定义事件下的参数

value:自定义事件参数下的参数值

使用自定义事件的依赖条件

  1. 使用自定义事件功能请先登陆 【友盟+】官网 ,在 "统计分析->设置->事件" (子账户由于权限限制可能无法看到"设置"选项,请联系主帐号开通权限。)页面中添加相应的事件id(事件id可用英文或数字,不要使用中文和特殊字符且不能使用英文句号"."您可以使用下划线"_"),然后服务器才会对相应的事件请求进行处理。
  2. 自定义事件的代码需要放在Activity里的nResume--onPause之间,请在sdk初始化之后调用事件,不支持在service中统计。

计数事件

使用计数事件需要在后台添加事件时选择"计数事件"。

统计发生次数

在您希望跟踪的代码部分,调用如下方法:

MobclickAgent.onEvent(Context context, String eventId);

context指当前的Activity

eventId为当前统计的事件ID。

示例:统计微博应用中"转发"事件发生的次数,那么在转发的函数里调用

MobclickAgent.onEvent(mContext,"Forward");

统计点击行为各属性被触发的次数

考虑事件在不同属性上的取值,可以调用如下方法:

MobclickAgent.onEvent(Context context, String eventId, HashMap map);

map为当前事件的属性和取值(Key-Value键值对)。

示例:统计电商应用中"购买"事件发生的次数,以及购买的商品类型及数量,那么在购买的函数里调用:

HashMap<String,String> map = new HashMap<String,String>();
map.put("type","book");
map.put("quantity","3"); 
MobclickAgent.onEvent(mContext, "purchase", map);


计算事件

使用计算事件需要在后台添加事件时选择"计算事件"。

统计数值型变量的值的分布

统计一个数值类型的连续变量(该变量必须为整数),用户每次触发的数值的分布情况,如事件持续时间、每次付款金额等,可以调用如下方法:

MobclickAgent.onEventValue(Context context, String id, Map<String,String> m, int du)

id 为事件ID map 为当前事件的属性和取值 du 为当前事件的数值为当前事件的数值,取值范围是-2,147,483,648 到 +2,147,483,647 之间的有符号整数,即int 32类型,如果数据超出了该范围,会造成数据丢包,影响数据统计的准确性。

示例:统计一次音乐播放,包括音乐类型,作者和播放时长,可以在音乐播放结束后这么调用:

int duration = 12000; //开发者需要自己计算音乐播放时长
  Map<String, String> map_value = new HashMap<String, String>();
  map_value.put("type" , "popular" );
  map_value.put("artist" , "JJLin" );   
MobclickAgent.onEventValue(this, "music" , map_value, duration);


上面方法在Android统计分析V5.2.2之后(>=)才提供,之前的版本可以通过下面的方式封装计算事件:

public static void onEvent(Context context, String id, HashMap<String,String> m, long value){
    m.put("__ct__", String.valueOf(value));
    MobclickAgent.onEvent(context, id, m);
}


统计点击次数及各属性触发次数

计算事件除能够统计数值型的参数外还具有计数事件的所有功能, 详细说明

注意事项

  1. event id不能使用特殊字符,不建议使用中文,且长度不能超过128个字节;map中的key和value 都不能使用特殊字符,key 不能超过128个字节,value 不能超过256个字节。
  2. id, ts, du是保留字段,不能作为event id及key的名称。
  3. 每个应用至多添加500个自定义事件,每个event 的 key不能超过10个,每个key的取值不能超过1000个。如需要统计支付金额、使用时长等数值型的连续变量,请使用计算事件(不允许通过key-value结构来统计类似搜索关键词,网页链接等随机生成的字符串信息)。

错误统计

Android统计SDK从V4.6版本开始内建错误统计,不需要开发者再手动集成。

SDK通过Thread.UncaughtExceptionHandler 捕获程序崩溃日志,并在程序下次启动时发送到服务器。 如不需要错误统计功能,可通过此方法关闭

MobclickAgent.setCatchUncaughtExceptions(false); 

如果开发者自己捕获了错误,需要上传到【友盟+】服务器可以调用下面方法:

public static void reportError(Context context, String error)   
//或  
public static void reportError(Context context, Throwable e)

使用自定义错误,查看时请在错误列表页面选择【自定义错误】

错误统计的常见问题参见【友盟+】开发者社区: 【友盟+】错误分析常见问题汇总

其他API

  • MobclickAgent.setOpenGLContext(GL10 gl) 设置penGL 信息,辅助统计GPU 信息
  • MobclickAgent.onKillProcess(Context context) 如果开发者调用 Process.kill 或者 System.exit 之类的方法杀死进程,请务必在此之前调用此方法,用来保存统计数据。

测试与调试

确认如下内容

  • 确认已经在App对应的Application中调用初始化函数
  • 确认所需的权限都已经添加:INTERNET, READPHONESTATE
  • 确认APPKEY已经正确的写入AndroidManifest.xml
  • 确认所有的Activity中都调用了onResume和onPause方法
  • 确认测试手机(或者模拟器)已成功连入网络

使用集成测试服务(推荐)

什么是集成测试? 集成测试是通过收集和展示已注册测试设备发送的日志,来检验SDK集成有效性和完整性的一个服务。 所有由注册设备发送的应用日志将实时地进行展示,您可以方便地查看包括应用版本、渠道名称、自定义事件、页面访问情况等数据,提升集成与调试的工作效率。

注意: 使用集成测试之后,所有测试数据不会进入应用正式的统计后台,只能在"管理--集成测试--实时日志"里查看,您不必再担心因为测试而导致的数据污染问题,让数据更加真实有效的反应用户使用情况。

使用集成测试模式请先在程序入口处调用如下代码,打开调试模式:

UMConfigure.setLogEnabled(true);

使用集成测试请点击 这里

使用普通测试流程

如果您不使用集成测试服务来测试数据,那您可以通过普通测试流程查看测试数据。 使用普通测试流程,您的测试数据会与用户的真实使用数据同时处理,从而导致数据污染。

使用普通测试流程,请先在程序入口添加以下代码打开调试模式:

UMConfigure.setLogEnabled(true);

打开调试模式后,您可以在logcat中查看您的数据是否成功发送到【友盟+】服务器,以及集成过程中的出错原因等,【友盟+】相关log的tag是MobclickAgent。

游戏集成文档

Android 游戏分析 SDK使用指南

调整场景类型设置接口

场景类型设置接口
MobclickAgent.setScenarioType(Context context, EScenarioType etype) etype是官方场景,有如下场景:

场景参数 场景类型
EScenarioType.E_UM_NORMAL 普通统计场景类型
EScenarioType.E_UM_GAME 游戏场景类型

UTDID相关

为防止冲突UTDID包单独提供,如果需要请导入UTDID包

介绍

【友盟+】游戏分析服务可以跟踪移动应用的用户属性及操作行为,并且通过【友盟+】的网站后台展示数据处理结果,帮助您调整产品、运营、推广策略的决策。我们目前支持iOS,Android平台。您可以在五分钟内轻松完成集成过程。 注意: 使用游戏统计分析需使用全新的【友盟+】APPKEY。如果有游戏或应用正在使用【友盟+】统计分析,请勿在中途替换成游戏统计分析!

特别提醒:我们建议开发者在注册账号时使用企业邮箱,避免使用个人邮箱注册,防止由于个人离职带来的问题,建议使用的账号形式 :umeng@企业域名、apps@企业域名、dev@企业域名。

基本功能集成指南

提示 请先在【友盟+】的管理后台中创建App,获得AppKey并导入SDK

  • 下载最新版SDK的zip包,将需要使用的jar包合并到本地工程libs子目录下。
  • 如您使用Android Studio开发,请在您的App对应build.gradle文件中加入对统计SDK和Common通用组件库的依赖:
dependencies
{
    compile file(dir:'libs',include:['umeng-analytics-7.x.0.jar'])
    compile file(dir:'libs',include:['umeng-common-1.x.0.jar'])
}

  • Eclipse用户右键工程根目录,选择Properties -> Java Build Path -> Libraries,然后点击Add External JARs... 选择指向jar的路径,点击OK,即导入成功。(ADT17及以上版本不需要手动导入)

  • 配置 AndroidManifest.xml

    <manifest……>
    <application ……>
    ……
    <activity ……/>
    <meta-data android:value="YOUR_APP_KEY" android:name="UMENG_APPKEY"></meta-data>
    <meta-data android:value="Channel ID" android:name="UMENG_CHANNEL"/>
    </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.ACCESS_WIFI_STATE"></uses-permission>
    </manifest>

权限说明

META-DATA 用途
UMENG_APPKEY 用来定位该应用程序的唯一性。
UMENG_CHANNEL 用来标注应用推广渠道,区分新用户的来源来查看统计,您可以使用20位以内的英文和数字的组合为渠道定名,替换value中的"Channel ID"。详见渠道统计。注意不要使用纯数字!
权限 用途
INTERNET(必须) 允许应用程序联网,以便向我们的服务器端发送数据。
READ_PHONE_STATE(必须) 获取用户手机的IMEI,用来唯一的标识用户。(如果您的应用会运行在无法读取IMEI的平板上,我们会将mac地址作为用户的唯一标识,请添加权限: android.permission.ACCESS_WIFI_STATE )
ACCESS_NETWORK_STATE(必须) 检测网络状态,【友盟+】SDK 1.6版本以上需要此权限。

添加代码 在游戏所在的Activity的onCreate方法调用 UMGameAgent.init(Context) 方法。在onResume方法中调用UMGameAgent.onResume(Context), onPause方法中调用

UMGameAgent.onPause(Context)
     public void onCreate(Bundle savedInstanceState) {
            super.onCreate(savedInstanceState);

        UMGameAgent.setDebugMode(true);//设置输出运行时日志
        UMGameAgent.init( this );
     }

     public void onResume() {
        super.onResume();
        UMGameAgent.onResume(this);
    }
    public void onPause() {
        super.onPause();
        UMGameAgent.onPause(this);
    }

说明

  1. Eclipse ADT 17 以上版本用户,请在工程目录下建一个文件夹libs,把jar包直接拷贝到这个文件夹下,再在>Eclipse里面刷新一下工程就好了。不要通过上述步骤手动添加jar包引用。 详情请参考Dealing with dependencies in Android projects.

  2. 方法将会自动地从AndroidManifest.xml文件里读取UMENG_APPKEY。

  3. 当用户两次使用之间间隔超过30秒时,将被认为是两个的独立的session(启动),例如用户回到home,或进入其他程序,经过一段时间后再返回之前的应用。

到此,基本统计功能集成已经完成。

XML设置appkey后需要在工程Application中手动调用初始化接口: UMConfigure.init(Context context, String appkey, String channel, int deviceType, String pushSecret); 或者 UMConfigure.init(Context context, int deviceType, String pushSecret); appkey和channel参数可以为null.

游戏接口集成

关卡统计集成

我们提供了一组方法来统计关卡相关的事件。

UMGameAgent.startLevel(String level); //level 为关卡ID(eg:level-01)
UMGameAgent.failLevel(String level);
UMGameAgent.finishLevel(String level);

在游戏开启新的关卡的时候调用 UMGameAgent.startLevel(level) 方法,在关卡失败的时候调用UMGameAgent.failLevel(level) 方法,在成功过关的时候调用 UMGameAgent.finishLevel(level) 方法。调用 failLevel 或 finishLevel 的时候会计算从 startLevel 开始的时长,作为这一关卡的耗时。level字段最好为非空可排序的字符串。 SDK 会默认减去程序切入后台的时间,可以设置 UMGameAgent.setTraceSleepTime(false); 来关闭默认设置,这样统计到的关卡时长是从 startLevel 到 failLvel(finishLevel) 之间的真实时长。 测试方法及报表对应关系请见产品使用文档。

注意 1. 目前每个游戏最多支持500个关卡。

真实消费统计

这部分API用来统计用户(或者玩家) 在游戏内付费的统计,包括购买虚拟币,道具等。

API 说明:

public static void pay(double money, double coin, int source) 

money 本次消费金额(非负数)

coin 本次消费的等值虚拟币(非负数)

source 支付渠道, 1 ~ 99 之间的整数, 1-20 已经被预先定义, 21~99 之间需要在网站设置。

如下表:

数值 含义
1 Google Play
2 支付宝
3 网银
4 财付通
5 移动通信
6 联通通信
7 电信通信
8 paypal

在游戏中充值或者购买虚拟币的时候调用此方法,比如通过支付宝用 10元钱 购买了 1000 个金币,可以这样调用:

UMGameAgent.pay(10,1000,2);

有些时候在游戏中会直接购买某个道具,比如10元购买 2个魔法药水,每个药水50个金币,可以调用下面的方法在付费的同时购买道具。

UMGameAgent.pay(10,"magic_bottle",2,50,2);

public static void pay(double money,String item , int number, double price,int source) 

money 本次消费的金额(非负数)

item 购买物品的ID(不能为空)

number 购买物品数量(非负数)

price 每个物品等值虚拟币的价格(非负数)

source 支付渠道 (见上表)

测试方法及报表对应关系请见产品使用文档。

带订单的真实消费

这部分API用来统计用户(或者玩家) 在游戏内付费的统计,可以统计不同的付费金额和币种,还支持统计订单ID等。

API 说明:

exchange(double currencyAmount, String currencyType, double virtualAmount, int channel, String orderId)

currencyAmount本次消费金额(非负数)

currencyType 本地消费金额的币种(可为空)

virtualAmount本次消费的等值虚拟币(非负数)

channel 支付渠道, 1 ~ 99 之间的整数, 1-20 已经被预先定义, 21~99 之间需要在网站设置。

orderId 付费的订单ID(可为空)

虚拟消费统计

游戏中所有虚拟消费,比如用金币购买某个道具都使用 buy 方法, 声明如下:

public static void buy(String item, int number,double price) 

item 购买物品的ID

number 购买物品数量

price 购买物品的单价(虚拟币)

比如在游戏中使用金币购买了1个头盔,一个头盔价值 1000 金币,可以这样统计:

UMGameAgent.buy("helmet", 1, 1000);

测试方法及报表对应关系请见产品使用文档。

物品消耗统计

游戏中的物品损耗,比如使用了2瓶魔法药水,每个需要50个虚拟币,可以这样统计:

UMGameAgent.use("magic_bottle", 2 , 50);
public static void use(String item, int number,double price)

item 消耗的物品ID

number 消耗物品数量

price 物品单价(虚拟币)

测试方法及报表对应关系请见产品使用文档。

注意 1. 目前每个游戏最多支持1000个道具的统计。

额外奖励

针对游戏中额外获得的虚拟币进行统计,比如系统赠送,节日奖励,打怪掉落。 比如连续5天登陆游戏奖励1000金币。

UMGameAgent.bonus(1000, 1);
public static void bonus(double coin, int trigger) 

coin 赠送的虚拟币数额

trigger 触发奖励的事件, 取值在 1~10 之间,“1”已经被预先定义为“系统奖励”, 2~10 需要在网站设置含义。

如果是掉落道具,比如掉落一把价值100金币的宝剑可以这样调用:

UMGameAgent.bonus("sword", 1, 100, 1);
public static void bonus(String item, int num, double price,int trigger) 

  • item 奖励物品ID

  • num 奖励物品数量

  • price 物品的虚拟币单价

  • trigger 触发奖励的事件, 取值在 1~10 之间,“1”已经被预先定义为“系统奖励”, 2~10 需要在网站设置含义。

如果在五一假期中举行登陆有奖活动,开发者想统计活动期间所赠送的金币数量,可以这样调用:

UMGameAgent.bonus(1000, 2);

在后台“设置”——“虚拟币来源管理”中将“2”这个事件设为节日奖励。即可看到相应的数据了。

注意:所有的浮点类型,只精确到百分位; 所有的数值类型不能为负数,否则不予处理。tigger的取值在1~10之间,“1”已经被预先定义为“系统奖励”,超过这个范围将不予处理。

玩家信息统计

增加玩家账号统计维度,同时可以追踪玩家的等级情况。以便结合关卡和付费数据整理出更有价值的用户。开发者应该在程序开始的地方尽早调用。

账号统计

注意:使用老版SDK中账号统计的开发者,请尽早跟新SDK并使用新接口

public static void onProfileSignIn(String ID) ;
public static void onProfileSignIn(String Provider, String ID) ;

ID:玩家账号ID,长度小于64字节 Provider:账号来源。如果玩家通过第三方账号登陆,可以调用此接口进行统计。不能以下划线"_"开头,使用大写字母和数字标识,长度小于32字节; 如果是上市公司,建议使用股票代码。

public static void onProfileSignOff();

账号登出时需调用此接口,调用之后不再发送账号相关内容。 当玩家使用游戏自有账号登录时,可以这样统计:

UMGameAgent.onProfileSignIn("playerID");

当玩家使用第三方账号(如新浪微博)登录时,可以这样统计:

UMGameAgent.onProfileSignIn("WB","playerID");

等级统计接口

当玩家建立角色或者升级时,需调用此接口 public static void setPlayerLevel(int level);

level:大于1的整数,最多统计1000个等级 当玩家从1级升至2级时,可以这样统计: UMGameAgent.setPlayerLevel(2);

高级功能集成指南

使用自定义事件

自定义事件可以实现在应用程序中埋点来统计用户的点击行为。自定义事件目前包括“计数事件”和“计算事件”,二者的区别以及详细说明请点击这里 ☺自定义事件使用中的问题请参见友盟+开发者社区:自定义事件常见问题

自定义事件字段说明

event id:自定义事件id key:自定义事件下的参数 value:自定义事件参数下的参数值

使用自定义事件的依赖条件

  1. 使用自定义事件功能请先登陆【友盟+】官网 , 在 “统计分析->设置->事件” (子账户由于权限限制可能无法看到“设置”选项,请联系主帐号开通权限。)页面中添加相应的事件id(事件id可用英文或数字,不建议使用中文),然后服务器才会对相应的事件请求进行处理。
  2. 自定义事件的代码需要放在Activity里的onResume方法后面,不支持放在onCreat()方法中。

计数事件

使用计数事件需要在后台添加事件时选择“计数事件”。

统计发生次数

在您希望跟踪的代码部分,调用如下方法: MobclickAgent.onEvent(Context context, String eventId);

context指当前的Activity,eventId为当前统计的事件ID。 示例:统计微博应用中"转发"事件发生的次数,那么在转发的函数里调用 MobclickAgent.onEvent(mContext,"Forward");

统计点击行为各属性被触发的次数

考虑事件在不同属性上的取值,可以调用如下方法: MobclickAgent.onEvent(Context context, String eventId, HashMap<String,String> map);

map 为当前事件的属性和取值(Key-Value键值对)。 示例:统计电商应用中“购买”事件发生的次数,以及购买的商品类型及数量,那么在购买的函数里调用:

HashMap<String,String> map = new HashMap<String,String>();
map.put("type","book");
map.put("quantity","3"); 
MobclickAgent.onEvent(mContext, "purchase", map);    

计算事件

使用计算事件需要在后台添加事件时选择“计算事件”。

统计数值型变量的值的分布

统计一个数值类型的连续变量(该变量必须为整数),用户每次触发的数值的分布情况,如事件持续时间、每次付款金额等,可以调用如下方法: MobclickAgent.onEventValue(Context context, String id, Map<String,String> m, int du)

id 为事件ID

map 为当前事件的属性和取值

du 为当前事件的数值为当前事件的数值,取值范围是-2,147,483,648 到 +2,147,483,647 之间的有符号整数,即int 32类型,如果数据超出了该范围,会造成数据丢包,影响数据统计的准确性。

示例:统计一次音乐播放,包括音乐类型,作者和播放时长,可以在音乐播放结束后这么调用:

int duration = 12000; //开发者需要自己计算音乐播放时长
Map<String, String> map_value = new HashMap<String, String>();
map_value.put("type", "popular");
map_value.put("artist", "JJLin"); 
MobclickAgent.onEventValue(this, "music", map_value, duration);

也可以使用下面方式封装计算事件:

public static void onEvent(Context context, String id, HashMap<String,String> m, long value){
    m.put("__ct__", String.valueOf(value));
    MobclickAgent.onEvent(context, id, m);
}

统计点击次数及各属性触发次数

计算事件除能够统计数值型的参数外还具有计数事件的所有功能,详细说明

注意事项

  1. event id不能使用特殊字符,不建议使用中文,且长度不能超过128个字节;map中的key和value 都不能使用特殊字符,key 不能超过128个字节,value 不能超过256个字节。
  2. id, ts, du是保留字段,不能作为event id及key的名称。
  3. 每个应用至多添加500个自定义事件,每个event 的 key不能超过10个,每个key的取值不能超过1000个。如需要统计支付金额、内容浏览数量等数值型的连续变量,请使用计算事件(不允许通过key-value结构来统计类似搜索关键词,网页链接等随机生成的字符串信息)。

使用分发渠道分析

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

注意: 每台设备仅记录首次安装激活的渠道,在其他渠道再次安装不会重复计量。 所以在测试不同的渠道的时候,请使用不同的设备来分别测试 不要改变'UMENG_CHANNEL',修改'Channel ID'为您的渠道名称,注意不能是纯数字(eg.value="GooglePlay") 配置AndroidManifest.XML添加下面代码

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

页面统计

页面统计集成正确,才能够获取正确的页面访问路径、访问深度(PV)的数据。 页面访问路径页面的数据为抽样统计(抽样比例为所有log的3%),数据量达到一定程度才会有数据,若您希望查看测试数据,请使用集成测试服务。

只由Activity构成的应用

如果您已完成上述步骤,那么SDK已默认统计了每个Activity的跳转路径。页面统计不需要再添加其他代码。

包含Activity、Fragment或View的应用

在程序入口处,调用 MobclickAgent.openActivityDurationTrack(false) 禁止默认的页面统计方式,这样将不会再自动统计Activity。 仍需在每个Activity中调用onResume()和onPause()方法。 然后在您要统计的Activity、Fragment或View中调用如下方法(pageName不能使用中文):

MobclickAgent.onPageStart(String pageName);
MobclickAgent.onPageEnd(String pageName);


应用程序页面的实现可能是基于Activity也可能是Fragment,推荐在相应的 onResume 和 onPause 方法中调用,比如 Activity :


public void onResume() {
    super.onResume();
    MobclickAgent.onPageStart("SplashScreen");
    MobclickAgent.onResume(this);
}
public void onPause() {
    super.onPause();
    MobclickAgent.onPageEnd("SplashScreen"); // 保证 onPageEnd 在onPause 之前调用,因为 onPause 中会保存信息 
    MobclickAgent.onPause(this);
}

比如 Fragment:

public void onResume() {
    super.onResume();
    MobclickAgent.onPageStart("MainScreen");
}
public void onPause() {
    super.onPause();
    MobclickAgent.onPageEnd("MainScreen"); 
}

这组方法的调用,需要保证线性不交叉,每个 start 都有一个 end 配对,如下: onPageStart ->onPageEnd-> onPageStart -> onPageEnd -> onPageStart ->onPageEnd

这样才能保证每个页面统计的正确,关于页面统计API的最佳实践说明见这里 。

其他API

MobclickAgent.setOpenGLContext(GL10 gl) //设置openGL 信息,辅助统计GPU 信息
MobclickAgent.onKillProcess(Context context) //如果开发者调用 Process.kill 或者System.exit 之类的方法杀死进程,请务必在此之前调用此方法,用来保存统计数据。

测试与调试

UMGameAgent 继承自 MobclickAgent 包含 MobclickAgent 提供的所有方法。

开启调试模式

UMConfigure.setLogEnabled(true);

调试步骤

  1. 确认所需的权限都已经添加:INTERNET, READ_PHONE_STATE
  2. 确认APPKEY已经正确的写入Androidmanifest.xml
  3. 确认所有的Activity中都调用了onResume和onPause方法
  4. 确认测试手机(或者模拟器)已成功连入网络
  5. 启动应用程序,几分钟之后您应该已经可以看到相应的报表.
  6. 如果几分钟后报表中仍然没有收到数据,请与我们的技术支持联系 点击链接 点击页面右上方的【人工云客服】选择对应产品入口[周一至周五9:00-18:00].
  7. 常见错误汇集

其他

  1. UMConfigure.setDebugMode(boolean enable) 设置是否debug模式,在debug模式下,会有log输出,方便调试 (默认true)
  2. UMGameAgent.setAutoLocation(boolean enable) 设置是否允许收集地理位置信息 (默认true)
  3. UMGameAgent.setSessionContinueMillis(long interval) 设置session启动的沉默参数,详见30秒规则 (默认30000)
  4. UMGameAgent.openActivityDurationTrack(boolean enable) 设置是否打开页面路径访问功能(默认打开)
  5. UMGameAgent.setOpenGLContext(GL10 gl) 设置openGL 信息,辅助统计GPU 信息
  6. UMGameAgent.onKillProcess(Context context) 如果开发者调用 Process.kill 或者 System.exit 之类的方法杀死进程,请务必再次之前调用此方法,用来保存统计数据。
  7. UMGameAgent.reportError(Context context,String error) 此方法会把传入的错误信息发回服务器

技术支持

点击访问:【友盟+】云客服:点击链接 (在线时间:周一至周五9:00-18:00) Email:support@umeng.com请发邮件至support@umeng.com,我们会尽快回复您。 为了能够尽快响应您的反馈,请提供您的appkey及log中的详细出错日志,您所提供的内容越详细越有助于我们帮您解决问题。