小米统计服务产品说明
如果您在集成过程中遇到任何问题，都可以添加QQ群：385428920 ，群中会有工程师解答您的问题。
1. 服务概况
小米统计服务是一项面向移动应用开发者的数据统计服务，目前支持Android和iOS两大平台。 开发者集成小米统计服务SDK并启用统计服务后，应用的数据将通过网络传输给小米统计服务的服务器，开发者通过小米统计服务提供的统计后台可以查看数据的统计分析结果，为应用的体验优化和运营推广提供数据参考。 使用小米统计服务可以实现：
- 了解应用的整体概况；
- 分析用户参与情况和设备属性信息；
- 对比参看渠道推广的数量和质量；
- 通过自定义事件可以定制化地统计用户各类操作和属性数据；
- 将具有共同特征的用户标记为一个用户群后，可以查看该用户群的各项数据统计指标
- 查看报表时可以按照渠道、版本和用户群进行组合筛选 ，并支持同时查看多组筛选
- 数据支持导出CSV文件
2. 主要报表
2.1 应用概况
目标
快速了解应用的核心指标
主要内容
昨日用户概况：展示累计总用户数、新增用户数、日活用户数、启动次数和月活用户数的昨日数据，并与前一天比较日变化比例。
今日实时数据：应用的新增用户和启动次数可以实时查看今日每小时的数据，还可以与昨天、7天前和30天前的数据进行对比。
趋势数据：展示新增用户、日活用户和启动次数这三个指标最近一段时间内的趋势变化情况。
2个渠道排行：基于昨日的数据，提供了新增用户TOP10渠道和日活用户TOP10渠道的排行。
常见问题
新增用户是如何定义的？
新增用户即安装该应用的新增设备，卸载重装或清除应用数据后也会被认为是一个新增用户。
2.2 用户参与
目标：详细展示用户新增、活跃、留存和使用等用户参与指标的数据变化情况，为开发者日常的产品运营提供数据参考。
2.2.1 新增与启动
该报表展示了新增用户、启动次数、人均启动次数和总用户的趋势变化，支持按照版本、渠道和用户群的组合筛选。
常见问题
如何定义启动次数？
启动次数指应用启动在前台的次数，iOS应用退到后台即认为结束一次启动，Android应用相邻2次启动的时间间隔如果在30秒内会视为一次启动。
2.2.2 活跃详情
该报表提供应用的日活用户、周活用户和月活用户的趋势统计，支持按照版本、渠道和用户群的组合筛选。
日活用户：当日至少启动过一次应用的设备数。
周活用户：当日之前的7天内（包括当日）至少启动过一次应用的设备数。
月活用户：当日之前的30天内（包括当日）至少启动过一次应用的设备数。
2.2.3 新用户留存
该报表提供的是针对应用新增用户的留存情况统计，支持按照版本、渠道和用户群的组合筛选。
留存率的定义为统计日新增用户中，在新增日后第N天启动过应用的用户比例即为统计日新增用户的第N日留存率，简称N日留存。
2.2.4 使用时长
该报表分为分布和趋势两大部分。
第一部分提供了昨日使用时长的2个区间分布：用户使用时长分布即当日活跃用户的使用时长分布；单次使用时长分布即当日每次启动的使用时长分布。
开发者还可以直接添加对比日期，来对比不同时间里使用时长分布的变化情况。
第二部分提供了人均使用时长和次均使用时长的趋势统计，支持按照版本、渠道和用户群的组合筛选。
2.2.5 版本分布
该报表中提供了各个版本的核心数据，支持按照渠道和用户群的组合筛选。
趋势图中展示的是当前所选时段中最后一日的日活用户数排名前五的版本的各项数据，支持添加对比版本进行比较；详细数据表格内提供了在统计日内历史所有版本的核心数据指标。
常见问题
新增用户和升级用户的定义有什么不同？
新增用户指第一次启用此应用的用户，卸载重装或清除数据后再使用会视为新增用户。升级用户指从别的版本升级到此版本的用户。
也就是说，新增用户是应用的新用户，而升级用户只是该版本的新用户，对应用来说并不是新用户。
2.2.6 页面访问
该报表提供了应用内所有页面访问次数和人数的统计，支持按照版本、渠道和用户群的组合筛选。
趋势图中展示了统计日当日访问次数排行前五的页面及其访问数据。详细数据表格中展示了应用每个页面的访问次数、访问人数以及在整个应用中的占比。
2.3 渠道统计
目标：让开发者可以横向对比不同渠道用户的数量和质量数据。
主要内容
这部分报表中提供了各个渠道的核心数据，支持按照版本和用户群的组合筛选。
趋势图中展示的是当前所选时段中最后一日的日活用户数排名前五的渠道的各项数据，支持添加对比渠道进行比较；详细数据表格内提供了在统计日内历史所有渠道的核心数据指标。
2.3 事件统计
目标：帮助开发者定制化地统计用户操作或属性信息，为一个操作或特征建立一个对应的自定义事件，就可以统计针对该操作或特征的用户行为，统计结果还支持渠道和版本的组合筛选。
主要内容
自定义事件为应用自行上报的打点统计，具体包括四种类型：字符串属性事件、数值属性事件、计数事件和计算事件，事件数据均支持按照渠道和版本的组合筛选。
2.4.1. 字符串属性事件
此类事件用于记录一个用户（对应到设备）的某个属性值，如性别，一个用户拥有性别这个事件对应的一个值，如果该用户再次提交了这个事件的其他值就以新的值覆盖旧的。 此类事件的值是作为字符串保存的，没有数值意义。
此类事件提供了统计日当日人数（当天完成了该事件的去重设备数）、累计人数（截止当日完成过该事件的累计去重设备数）和事件的取值分布。
2.4.2. 数值属性事件
与字符串属性事件使用场景类似，数值属性事件也是用来记录用户的属性值，同一个用户提交的新值会覆盖旧值。不同之处在于数值属性事件的值是作为数值保存的，有数值意义，比如年龄。
此类事件提供了当日人数、累计人数、累计人均取值（即截止当日该事件上报取值的总和/该事件的累计人数*100%）和取值分布图。
2.4.3. 计数事件
此类事件用于记录一个事件累计发生的数量，每发生一次就增加1，经典的使用场景是记录各种按钮的点击事件。
计数事件提供了发生的次数、人数和人均次数三个指标。
2.4.4. 计算事件
此类事件不仅可以记录事件发送的数量，还能记录每次发生的数值。比如充值行为就是一个典型的计算事件，开发者既需要知道充值行为发生的次数、人数和人均次数，也需要知道充值的总金额、人均充值金额和次均充值金额。
计算事件除了具有计数事件的发生次数、人数和人均次数指标之外，还有取值总和、人均取值和次均取值三个指标。
2.5. 设备属性
目标：提供用户设备基本信息的收集和统计，帮助开发者了解用户设备属性、网络使用情况和地区分布。
2.5.1. 设备属性
该报表分为三个部分，分别提供了机型、分辨率和系统版本三项数据。
以机型数据为例，趋势图中展示的是统计日当日的新增用户和日活用户排名前十的机型；详细数据表格内提供了在统计日内所有机型的新增用户和日活用户数。
2.5.2. 网络与运营商
该报表分为两个部分，分别提供了联网方式和运营商三项数据。运营商统计与设备属性统计的报表结构一致。网络统计比较特殊，统计的指标是不同联网方式下的启动次数，并支持添加对比日期。
2.5.3. 地区分布
提供国家和国内省份的新增用户和日活用户数据，帮助开发者了解用户的地区分布情况。
3. 定制功能
3.1. 自定义事件
详见2.4事件统计的表述
3.2. 用户群
用户群是开发者自定义的筛选条件，可以用来筛选各类数据指标。
用户群的定义建立在自定义事件的基础上，每个应用最多可同时拥有5个用户群，用户群建立后只能删除不能编辑。
如何新建用户群？
在设置-用户群页面内点击“新建用户群”按钮
在新建用户群的页面内根据地区或应用当下已上报的自定义事件去设计用户群中的用户需要满足的条件，可以同时使用多个自定义事件，即要求同时满足多个事件条件。
如何使用不同类型事件设计用户群条件？
- 字符串属性事件
可指定该事件上报过的取值，可多选，多选是任一一个取值满足即符合条件的意思。
例如使用字符串属性事件“教育程度”，取值规则中选择了“本科”、“研究生”两个取值，含义是说用户的教育程度是本科或研究生的就符合该用户群条件。
- 数值属性事件
可指定取值“大于等于某数”或“小于等于某数”。
例如使用数值属性事件“年龄”，取值规则设定为“大于等于20”，含义是说大于等于20岁的用户符合该条件。
- 计数事件
可指定当日最少发生次数或最多发生次数。
例如使用计数事件“点击地理位置按钮”，取值规则设定为最少发生1次，含义是说当天至少点过1次地理位置按钮的用户符合该条件。
- 计算事件：
可指定以下取值规则：当日最少发生次数、最多发生次数、当日取值大于等于某数、当日取值等于某数或当日取值小于等于某数。
例如使用计算事件“充值金额”，取值规则如设定为最少发生1次，即当天至少充值过1次的用户符合该条件；取值规则如设定为当日取值大于等于100，即当天充值金额当于等于100的用户符合该条件。
4. 常见问题
1、小米统计的使用范围
小米统计目前支持Android和iOS两大平台。
2、如何启用小米统计？
如果开发者在dev.xiaomi.com下已有应用，可以直接在应用的页面内进入小米统计服务来启用服务。否则就需要您新建一个应用再启用小米统计服务。
启用后开发者就可以进行统计SDK的集成测试了，我们不同平台的SDK文档地址如下：
Android版：http://dev.xiaomi.com/doc/p=3995/index.html
iOS版：http://dev.xiaomi.com/doc/p=3998/index.html
3、小米统计是否会收费？
小米统计作为小米开发者服务中的基础服务会永久免费。
4、有些统计指标我不太理解该怎么办？
-
可以查看页面上的？内有当页统计指标的说明
-
可以查看小米统计的产品说明文档：http://dev.xiaomi.com/doc/?p=4003
-
可以联系小米统计的产品经理：吴青 wuqing@xiaomi.com
5. 附录：全部统计指标定义
| 指标名称 | 指标定义 |
|---|---|
| 用户 | 即独立设备，Android按设备的IMEI、序列号和Android ID确定的唯一设备；iOS按照设备的UDID确定。 |
| 累计总用户数 | 开始使用小米统计服务后所有新增用户的总和。 |
| 新增用户数 | 新增的设备数，卸载重装或清除应用数据后也会算作一个新增用户。 |
| 升级用户 | 从别的版本升级到此版本的用户。 |
| 日活用户数 | 当日至少启动过一次应用的设备数。 |
| 启动次数 | 当日应用启动在前台的次数，iOS应用退到后台即认为结束一次启动，Android应用相邻2次启动的时间间隔如果在30秒内会视为一次启动。 |
| 人均启动次数 | 日活用户的平均启动次数。 |
| 周活用户数 | 统计日之前的7天内（包括统计日当日）至少启动过一次应用的设备数。 |
| 月活用户数 | 统计日之前的30天内（包括统计日当日）至少启动过一次应用的设备数。 |
| 次日留存率 | 某日新增用户中，在新增日后的第一天启动过应用的用户比例。 |
| 3日留存率 | 某日新增用户中，在新增日后的第三天启动过应用的用户比例。 |
| 7日留存率 | 某日新增用户中，在新增日后的第七天启动过应用的用户比例。 |
| 30日留存率 | 某日新增用户中，在新增日后的第三十天启动过应用的用户比例。 |
| 使用时长 | 用户在前台使用应用的时间长度。 |
| 用户使用时长分布 | 统计日活跃用户的使用时长分布 |
| 单次使用时长分布 | 统计日每次启动的使用时长分布 |
| 人均使用时长 | 统计日活跃用户平均每人使用应用的时间，精确到秒 |
| 次均使用时长 | 统计日应用启动中平均每次启动的使用时间，精确到秒 |
| 页面 | Android按activity或fragment上报，iOS按 UIViewController的名字或自定义上报 |
| 渠道 | 在SDK初始化时由应用客户端设置的渠道信息 |
| 版本 | 应用当前版本号 |
| 访问次数 | 该页面访问PV |
| 访问人数 | 该页面访问UV |
| 自定义事件 | 应用自行上报的打点统计，分为4种类型：字符串属性事件、数值属性事件、计数事件和计算事件。 |
| 字符串属性事件 | 此类事件用于记录一个用户（对应到设备）的某个属性值，如性别，一个用户拥有性别这个事件对应的一个值，如果该用户再次提交了这个事件的其他值就以新的值覆盖旧的。此类事件的值是作为字符串保存的，没有数值意义。 |
| 数值属性事件 | 与字符串属性事件使用场景类似，数值属性事件也是用来记录用户的属性值，同一个用户提交的新值会覆盖旧值。不同之处在于数值属性事件的值是作为数值保存的，有数值意义，比如年龄。 |
| 计数事件 | 此类事件用于记录一个事件累计发生的数量，每发生一次就增加1，经典的使用场景是记录各种按钮的点击事件。计数事件我们提供发生的次数、人数和人均次数三个指标。 |
| 计算事件 | 此类事件不仅可以记录事件发送的数量，还能记录每次发生的数值。除了具有计数事件的发生次数、人数和人均次数指标外，计算事件还有取值总和、人均取值和次均取值三个指标。比如充值行为就是一个典型的计算事件，开发者既需要知道充值行为发生的次数、人数和人均次数，也需要知道充值的总金额、人均充值金额和次均充值金额。 |
| 用户群 | 用户群是开发者自定义的筛选条件，可以用来筛选各类数据指标。用户群的定义建立在自定义事件的基础上，每个应用最多可同时拥有5个用户群。 |
This entry was posted in 技术文档 on 2014 年 9 月 4 日 by 吴, 青.
小米统计服务安卓客户端SDK使用指南
如果您在集成过程中遇到任何问题，都可以添加QQ群：385428920 ，群中会有工程师解答您的问题。
1. 客户端SDK功能概述
在使用小米统计服务前，开发者需要先登录小米开发者网站http://dev.xiaomi.com ，注册app，申请AppId, AppKey。其中AppId和AppKey是客户端的身份标识，在客户端SDK初始化时使用。然后下载最新的SDK压缩包，其中包括了Android SDK和Android Demo。Android版SDK以jar形式提供， 第三方APP只需要添加少量代码和配置，即可完成接入小米统计服务。
统计服务Android客户端SDK所有的接口都封装在一个MiStatInterface的抽象类的静态方法中，主要功能接口请参考第3节API说明。应用在启动时，需要调用initialize方法来初始化统计服务，之后便可按照统计的业务需求，调用统计数据上报接口上报统计打点。 SDK提供了接口给开发者来设置向小米统计服务器上报统计数据的策略，开发者可以在任意时候调用修改策略。客户端SDK上报的数据包括默认事件统计、session统计（用于统计app的活跃度、打开频率、使用时长等）、页面访问统计和自定义事件统计。
2. SDK使用说明
本节主要介绍如何配置和使用小米统计SDK，开发者也可以参照SDK中的demo来配置和使用小米统计SDK。
2.1. 配置AndroidManifest.xml文件
- 小米推送服务SDK支持的最低安卓版本为2.2。
<uses-sdk android:minSdkVersion="8"/>
- 推送服务需要的权限列表
<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" />
对应的4种权限，用途如下：
- 网络访问权限，需要联网以便于向小米统计服务端上报统计数据。
- 查看网络状态，用于根据不同的网络环境，选择相应的上报策略。同时也需要上报当前的网络环境用于后台统计展示。
- 读取手机状态和身份，用于获取设备的唯一标识，为当前设备生成一个唯一设备ID。
2.2. 初始化统计服务
应用启动时，需要调用统计SDK中的初始化方法，传入appID、appKey等身份验证参数和应用对应的渠道号。在调用其他统计服务相关API前，必须调用本方法初始化统计服务，建议您在程序Application的onCreate中初始化小米统计服务。
MiStatInterface.initialize(this, MY_APPID, MY_APP_KEY, CHANNEL);
3.app常规数据统计
本节主要介绍如何设置数据上报策略，如何记录页面访问行为和用户自定义事件。本节也介绍了通过集成测试模块验证SDK是否集成成功的方法。
3.1. 数据上报策略
小米统计服务SDK会先把数据记录缓存在本地，然后根据开发者设定的数据上报策略，触发上报流程。SDK中提供了一系列数据上报策略供开发者选择，这些策略包括：
-
UPLOAD_POLICY_REALTIME 实时上报。每当有一条新的记录，就会激发一次上报。
-
UPLOAD_POLICY_WIFI_ONLY 只在WIFI下上报。当设备处于WIFI连接时实时上报，否则不上报记录。
-
UPLOAD_POLICY_BATCH 批量上报。当记录在本地累积超过一个固定值时（50条），会触发一次上报。
-
UPLOAD_POLICY_WHILE_INITIALIZE 启动时候上报。每次应用启动（调用initialize方法）时候，会将上一次应用使用产生的数据记录打包上报。
-
UPLOAD_POLICY_INTERVAL 指定时间间隔上报。开发者可以指定从5分钟-1天之间的任意时间间隔上报数据记录。需要注意，由于SDK并没有使用安卓的实时唤醒机制，因此采用此策略上报，SDK做不到严格的遵守开发者设定的间隔，而会根据应用数据采集的频率和设备休眠策略，会有一定的偏差。
-
UPLOAD_POLICY_DEVELOPMENT 调试模式。使用此策略，只有开发者手动调用一个接口才会触发上报，否则在任何情况下都不上报。SDK中提供了一个triggerUploadManually方法用于手动触发。这种策略主要用于开发者调试时候可手动控制上报时机，便于做数据对比。
小米统计服务的本地缓存最长会保存3天，只要在3天内上报流程被触发，就会将本地之前没上报成功的所有数据打包上报。如果数据上报成功，则会把已经成功的数据从本地删除。
设置上报策略的代码示例如下：
MiStatInterface.setUploadPolicy(UPLOAD_POLICY_REALTIME, 0);
3.2. 默认事件
为了提供一些app所共有的统计维度，小米统计SDK会默认采集如下一些应用信息作为事件上报到小米统计后台：
表 1. 默认上报事件
| 事件名称 | 事件说明 | 上报时机 |
|---|---|---|
| 新增 | 用于实时统计应用的新增人数 | 应用第一次初始化统计服务 |
| 版本升级 | 用于统计每个版本的升级人数和升级时间 | 应用每次版本更新后第一次启动 |
| 机型 | 用于统计机型分布，并可将机型设置为其它统计项的过滤条件 | 应用第一次初始化统计服务 |
| 安卓系统版本 | 用于统计版本分布，并可将版本设置为其它统计项过滤条件 应用第一次初始化统计服务 | |
| 系统语言 | 用于统计系统语言的分布 | 应用第一次初始化统计服务 |
| 运营商 | 用于统计运营商分布信息 | 应用第一次初始化统计服务 |
| IMEI | 用于标识某个特定的设备 | 应用第一次初始化统计服务 |
| 屏幕分辨率 | 用于统计屏幕分辨率的分布 | 应用第一次初始化统计服务 |
| App渠道号 | 用于统计应用渠道分布情况，并为其它统计项提供实时过滤 | 每次上报 |
| App版本号 | 用于统计应用版本分布情况，并为其它统计项提供实时过滤 | 每次上报 |
| 网络环境 用于统计用户在打开应用时候的网络分布情况 每次session上报 |
3.3. session
小米统计服务将从用户打开应用开始，到离开应用并且超过30秒结束，这一段时间我们定义为一个session。session主要用于开发者观察用户的使用时长、打开次数等统计项。为了统计session，需要开发者在用户进入应用每个界面（Activity）的时候，调用recordPageStart方法，在用户离开该界面的时候，调用recordPageEnd方法。我们建议将这两个调用分别放于应用所有的Activity的onResume和onPause方法中。示例代码如下：
public class MainActivity extends Activity {
@override
protected void onResume() {
super.onResume();
MiStatInterface.recordPageStart(this, "主界面");
}
protected void onPause() {
super.onPause();
MiStatInterface.recordPageEnd();
}
}
小米统计服务SDK会根据每个Activity进入-退出的时间，自动计算出用户使用的session数据。
3.4. 页面访问
在记录session的同时，小米统计SDK也会记录下用户页面之间的跳转，每条页面跳转的数据记录了一个session当中所有的页面访问记录。页面访问的数据同样通过recordPageStart和recordPageEnd这两个方法来记录，开发者可以为每个页面设置一个名称，作为recordPageStart的第二个参数传入：
MiStatInterface.recordPageStart(activity, MY_PAGE_NAME);
如果页面名称传入空，则SDK会直接采用activity的完整类名来作为页面名称。
在android4.0以及之后的版本中，很多界面都采用Fragment方式来开发界面，这种方式下，Activity作为一个容器，不会对应某个特定的界面，因此会对页面访问的统计产生一些错误数据。这种情况下我们建议只在Fragment的onResume和onPause中添加recordPageStart和recordPageEnd方法。示例代码如下：
public class MyFragmentActivity extends FragmentActivity {
@override
protected void onResume() {
super.onResume();
// 这是一个fragment的容器activity，在onResume中不需要调用小米统计
// 服务的recordPageStart方法
...
}
protected void onPause() {
super.onPause();
...
}
}
public class MyFragment extends Fragment {
@override
protected void onResume() {
super.onResume();
// 在fragment中的调用用于记录页面访问信息
MiStatInterface.recordPageStart(getActivity(), "主界面");
...
}
protected void onPause() {
super.onPause();
MiStatInterface.recordPageEnd();
...
}
}
3.5. 自定义事件
除了默认事件、session和页面访问外，小米统计服务提供了自定义事件的上报。开发者可结合应用的业务逻辑，添加自定义事件的统计。每个自定义事件有如下4个属性：类别（category）、主键（key）、值（value）和类型（type）。这4个参数的的含义和作用如下：
-
category
自定义事件的类别，开发者可使用该参数对自定义打点做整理归类，方便在有大量的自定义事件时在数据统计后台快速定位到相应的事件。类别是一个可选的参数，如果这个值为空，统计SDK会将该事件放入默认的类别中。
-
key自定义事件的主键，作为该事件的唯一标识。
-
value 自定义事件的值，根据事件类型不同，值会有字符串和数值两种类型。
-
type 自定义事件的类型。根据不同的业务上报逻辑，我们将自定义事件分成如下4种类型：计数（count）、计算（calculate）、字符串属性（string property）和数值属性（numeric property）。每个类型的详细解释如下：
计数和计算类型的事件，除了上述属性之外，还可以增加事件参数（参见API说明部分）。事件参数可以以更丰富的维度展示与该事件相关的数据。比如，游戏应用中的一种消费行为，开发者对发生该事件的用户性别，等级，年龄等感兴趣，就可以将性别，年龄，等级均设置为消费事件的参数；这样，对于该消费事件，除了统计发生次数外，还会展示事件发生时，用户的性别，年龄和等级的分布情况。
每个自定义事件最多可以传10个不同的参数。
3.5.1. 计数类型
计数类型事件通常用来描述一个事件累积发生的次数，适用的场景如按钮点击、界面进入、用户输入等。这类事件的上报代码如下：
MiStatInterface.recordCountEvent("Button_Click", "Button_OK_click");
每次调用需要传入分类和主键，这类事件的value都隐式的被设置成数字“1”，不需要单独设置。统计后台会对这类事件做总发生次数、总覆盖用户数等统计计算。
3.5.2. 计算类型
计算类型事件通常用来描述一个带数值的事件的发生，适用的场景如用户消费事件，附带的数值是每次消费的金额；下载文件事件，附带的数值是每次下载消耗的时长等。这类事件的上报代码如下：
MiStatInterface.recordCalculateEvent(“user_pay”, "buy_ebook", 20);
每次调用需要传入分类、主键和对应数值，其中数值是一个long型的整数。统计后台会对这类事件做累加、分布、按次平均、按人平均等统计计算。
3.5.3. 字符串属性类型
字符串属性类型通常用来描述某个具备字符串特征的属性，适用的场景如用户性别、用户职业、用户爱好等，这类属性的取值是一个字符串值。这类事件的上报代码如下：
MiStatInterface.recordStringPropertyEvent(“user_profile”, "genda", "female");
每次调用需要传入分类、主键和字符串值。对于同一主键的字符串属性，一个设备只会保存一个，即，一个设备上报多次同一个主键的字符串属性类型，统计服务后台只会保存和统计最新的属性。
3.5.4. 数值属性类型
数值属性类型通常用来描述某个具备数值特征的属性，适用的场景如用户年龄、工作年限、游戏等级等，这类属性的取值是一个整型数值。这类事件的上报代码如下：
MiStatInterface.recordNumericEvent(“user_profile”, "age", 26);
每次调用需要传入分类、主键和数值。和字符串属性一样，对于同一主键的数值属性，一个设备只会保存一个，即，一个设备上报多次同一个主键的数值属性类型，统计服务后台只会保存和统计最新的属性。
3.6. 集成测试
我们提供了集成测试模块，通过简单的几个步骤，即可以观察到通过小米统计上传的数据，判断统计是否生效；集成测试的数据和正式数据完全隔离，互不干扰。具体步骤如下：
- 步骤一，增加测试设备。在统计数据网站中，点击进入“集成测试”项。通过在手机端调用MiStatInterface#getDeviceID(Context context)获取设备标示，增加到测试设备中。
图1.添加测试设备 - 步骤二，客户端上传统计数据，新增的测试设备统计数据会自动展示在测试日志列表中，点击可以查看该统计日志的详情。
图2.查看设备统计数据
图 3. 统计日志详情
4.崩溃日志收集
应用程序发布后，在使用过程中，可能因为各种原因而崩溃。小米统计SDK内置了崩溃日志上报功能，开发者通过调用MiStatInterface#enableExceptionCatcher(boolean uploadImmediately)即可开启该功能。根据参数不同，开发者可以选择崩溃后实时上传崩溃日志，也可以选择和常规统计数据相同的上报策略。
5. API说明
小米统计服务android版SDK所有的接口都以静态方法的形式封装在MiStatInterface这个类中。这个类的定义如下：
public abstract class
extends Object
java.lang.Object
↳ com.xiaomi.mistatistic.sdk.MiStatInterface
其中每个方法的参数详细描述如下：
5.1. public static void initialize(Context context, String appID, String appKey, String channel)
初始化统计服务接口，必须在所有数据记录之前调用。推荐将该方法放入Application对象或者主Activity的onCreate方法中。
表 2. initialize函数参数列表 参数列表 |参数说明 ---|--- context （必填） | Android平台上app的上下文，建议传入当前app的application context appID （必填） | 在开发者网站上注册时生成的，小米统计服务颁发给app的唯一标识 appKey （必填） | 在开发者网站上注册时生成的，与appID相对应，用于验证appID是否合法 channel （选填） |app的渠道信息，便于后台可按照渠道来统计应用的各项数据
5.2. public static void setUploadPolicy(int policy, long interval)
设置上报策略接口。
表 3. setUploadPolicy函数参数列表 参数列表 | 参数说明 --|--- policy （必填） |所需要设置的上报策略类型，取值可从UPLOAD_POLICY_REALTIME、UPLOAD_POLICY_WIFI_ONLY、UPLOAD_POLICY_BATCH、UPLOAD_POLICY_WHILE_INITIALIZE、UPLOAD_POLICY_INTERVAL、UPLOAD_POLICY_DEVELOPMENT中选取 interval （选填） |时间间隔。当policy设置为UPLOAD_POLICY_INTERVAL的时候，该参数生效。
5.3. public static void recordPageStart(Activity act, String pageName)
记录界面进入事件，建议放在Activity或Fragment的onResume方法中调用。
表 4. recordPageStart函数参数列表 参数列表 |参数说明 ---|--- act （必填） | 所在界面的Activity实例 pageName（选填） | 页面的名称，如果是NULL或空字符串，则SDK会使用act的完整包名作为当前页面的名称。
5.4. public static void recordPageEnd()
记录当前页面访问结束。
5.5. public static void recordCountEvent(String category, String key)
记录自定义计数事件。
表 5. recordCountEvent函数参数列表 参数列表 | 参数说明 ---|--- category （选填） | 事件的分类。 key （必填） | 事件的主键，是这个自定义事件的唯一标识。
5.6. public static void recordCountEvent(String category, String key, Map<String, String>params)
记录带参数的自定义计数事件。
表 6. recordCountEvent函数参数列表 参数列表 | 参数说明 ---|--- category （选填） | 事件的分类。 key （必填） | 事件的主键，是这个自定义事件的唯一标识。 params(选填)| 事件的参数，支持不超过10个不同的参数。
5.7. public static void recordCalculateEvent(String category, String key, long value)
记录自定义计算事件。
表 7. recordCalculateEvent函数参数列表 参数列表 | 参数说明 ---|--- category （选填） | 事件的分类。 key （必填） | 事件的主键，是这个自定义事件的唯一标识。 value(必填)| 事件的值，是一个long型的函数。
5.8. public static void recordCalculateEvent(String category, String key, long value, Map<String, String> params)
记录带参数的自定义计算事件。 表 8. recordCalculateEvent函数参数列表 参数列表 | 参数说明 ---|--- category （选填） | 事件的分类。 key （必填） | 事件的主键，是这个自定义事件的唯一标识。 value(必填)| 事件的值，是一个long型的函数。 params(选填)| 事件的参数，支持不超过10个不同的参数。
5.9. public static void recordStringPropertyEvent(String category, String key, String value)
记录自定义字符串属性事件。
表 9. recordStringPropertyEvent函数参数列表 参数列表 | 参数说明 ---|--- category （选填） | 事件的分类。 key （必填） | 事件的主键，是这个自定义事件的唯一标识。 value(必填)| 事件的值，是一个字符串函数。
5.10. public static void recordNumericPropertyEvent(String category, String key, long value)
记录自定义数值属性事件。
表 10. recordNumericPropertyEvent函数参数列表 参数列表 | 参数说明 ---|--- category （选填） | 事件的分类。 key （必填） | 事件的主键，是这个自定义事件的唯一标识。 value(必填)| 事件的值，是一个long型的函数。
5.11. public static void triggerUploadManually()
手动触发上报，该调用仅会在当上报策略设置为UPLOAD_POLICY_DEVELOPMENT时起作用。
5.12. public static final String getDeviceID(Context context)
获取设备标示。在接入SDK时, 通过此方法获取设备标示，添加到测试设备中，就可以在测试数据列表中看到该设备上报的统计数据。
5.13. enableExceptionCatcher(boolean uploadImmediately)
开启app崩溃日志上传功能。为了能够采集app所有的崩溃，建议在Application的onCreate方法中调用本方法。
This entry was posted in 技术文档 on 2014 年 9 月 4 日 by 吴, 青.
小米统计服务iOS客户端SDK使用指南
如果您在集成过程中遇到任何问题，都可以添加QQ群：385428920 ，群中会有工程师解答您的问题。
1. 客户端SDK功能概述
在使用小米统计服务前，开发者需要先登录小米开发者网站http://dev.xiaomi.com ，注册app，申请AppId, AppKey。其中AppId和AppKey是客户端的身份标识，在客户端SDK初始化时使用。然后下载最新的SDK压缩包，其中包括了iOS SDK和iOS Demo。SDK以.a动态链接库的形式提供， 开发者只需在原有编码基础上添加少许代码，即可完成接入小米统计服务。
统计服务iOS客户端SDK所有的接口都封装在MiStatSDK中，主要功能接口请参考第3节API说明。应用在启动时，需要调用+ (void)registerMiStat:(NSString*)channel 方法来初始化统计服务，之后便可按照统计的业务需求，调用统计数据上报接口上报统计打点。 SDK提供了接口给开发者来设置向小米统计服务器上报统计数据的策略，开发者可以在任意时候调用修改策略。客户端SDK上报的数据包括默认事件统计、session统计（用于统计app的活跃度、打开频率、使用时长等）、页面访问统计和自定义事件统计。
2. SDK使用说明
本节主要介绍如何配置和使用小米统计SDK，开发者也可以参照SDK中的demo来配置和使用小米统计SDK。
2.1. 搭建XCode运行环境
我们的libMiStatSDK库文件同时包含i386、armv6和armv7的代码，所以libMiStatSDK将同时支持真机与模拟器。
- 小米统计服务iOS版支持的最低系统版本iOS4.3
- 添加libMiStatSDK.a , MiStatSDK.h 到工程
- 引入库libz.dylib，SystemConfiguration.framework，MobileCoreServices.framework (如果已经引入,请忽略)
2.2. 配置SDK运行参数
运行SDK注册小米统计服务的时候，需要使用AppId，AppKey，等参数来验证使用者的合法性。
- 打开工程下资源文件Info.plist
- 文件为源代码形式打开，添加以下信息
<dict>
<key>MiSDKAppID</key>
<string>1000888</string>
<key>MiSDKAppKey</key>
<string>500088888888</string>
</dict>
- MiSDKAppId, MiSDKAppKey为在小米开发者网站http://developer.xiaomi.com。注册App，申请的AppId,AppKey
3. 常规数据统计
3.1. 初始化统计服务
当应用启动时候，需要调用统计SDK中的初始化方法，应用对应的渠道号。
例如：
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[MiStatSDK registerMiStat:@"channel"];
}
3.2. 数据上报策略
小米统计服务SDK会先把数据记录缓存在本地，然后根据开发者设定的数据上报策略，触发上报流程。SDK中提供了一系列数据上报策略供开发者选择，这些策略包括：
-
UPLOAD_POLICY_TYPE_REALTIME 实时上报。每当有一条新的记录，就会激发一次上报。
-
UPLOAD_POLICY_TYPE_WIFI_ONLY 只在WIFI下上报。当设备处于WIFI连接时实时上报，否则不上报记录。
-
UPLOAD_POLICY_TYPE_LAUNCH 启动时候上报。每次应用启动时候，会将上一次应用使用产生的数据记录打包上报。
-
UPLOAD_POLICY_TYPE_INTERVAL 指定时间间隔上报。开发者可以指定从5分钟-1天之间的任意时间间隔上报数据记录。需要注意，采用此策略上报，SDK做不到严格的遵守开发者设定的间隔，而会根据应用数据采集的频率和设备休眠策略，会有一定的偏差。
-
UPLOAD_POLICY_TYPE_DEVELOPMENT 调试模式。使用此策略，只有开发者手动调用一个接口才会触发上报，否则在任何情况下都不上报。SDK中提供了一个+(void)triggerUploadManually;方法用于手动触发。这种策略主要用于开发者调试时候可手动控制上报时机，便于做数据对比。
小米统计服务的本地缓存最长会保存3天，只要在3天内上报流程被触发，就会将本地之前没上报成功的所有数据打包上报。如果数据上报成功，则会把已经成功的数据从本地删除。
设置上报策略的代码示例如下：
[MiStatSDK setUploadPolicy:UPLOAD_POLICY_TYPE_LAUNCH interval:0];
3.3. 默认事件
为了提供一些app所共有的统计维度，小米统计SDK会默认采集如下一些应用信息作为事件上报到小米统计后台：
表 1. 默认上报事件
| 事件名称 | 事件说明 | 上报时机 |
|---|---|---|
| 新增 | 用于实时统计应用的新增人数 | 应用第一次初始化统计服务 |
| 版本升级 | 用于统计每个版本的升级人数和升级时间 | 应用每次版本更新后第一次启动 |
| 机型 | 用于统计机型分布，并可将机型设置为其它统计项的过滤条件 | 应用第一次初始化统计服务 |
| 安卓系统版本 | 用于统计版本分布，并可将版本设置为其它统计项过滤条件 应用第一次初始化统计服务 | |
| 系统语言 | 用于统计系统语言的分布 | 应用第一次初始化统计服务 |
| 运营商 | 用于统计运营商分布信息 | 应用第一次初始化统计服务 |
| IMEI | 用于标识某个特定的设备 | 应用第一次初始化统计服务 |
| 屏幕分辨率 | 用于统计屏幕分辨率的分布 | 应用第一次初始化统计服务 |
| App渠道号 | 用于统计应用渠道分布情况，并为其它统计项提供实时过滤 | 每次上报 |
| App版本号 | 用于统计应用版本分布情况，并为其它统计项提供实时过滤 | 每次上报 |
| 网络环境 用于统计用户在打开应用时候的网络分布情况 每次session上报 |
3.4. session
小米统计服务将从用户打开应用开始，到离开应用并且超过30秒结束，这一段时间我们定义为一个session。session主要用于开发者观察用户的使用时长、打开次数等统计项。
SDK自动计算出用户使用的session数据。
3.5. 页面访问
在记录session的同时，小米统计SDK也会记录下用户页面之间的跳转，每条页面跳转的数据记录了用户在一个session当中所有的页面访问记录。
如果页面名称传入空，则SDK会直接采用activity的完整类名来作为页面名称。
示例代码如下：
- (void)viewDidAppear:(BOOL)animated
{
[MiStatSDK recordPage:@"UIViewController"];
}
3.6. 自定义事件
除了默认事件、session和页面访问外，小米统计服务提供了自定义事件的上报。开发者可结合应用的业务逻辑，添加自定义事件的统计。每个自定义事件有如下4个属性：类别（category）、主键（key）、值（value）和类型（type）。这4个参数的的含义和作用如下：
- category 自定义事件的类别，开发者可使用该参数对自定义打点做整理归类，方便在有大量的自定义事件时在数据统计后台快速定位到相应的事件。类别是一个可选的参数，如果这个值为空，统计SDK会将该事件放入默认的类别中。
- key 自定义事件的主键，作为该事件的唯一标识。
- value 自定义事件的值，根据事件类型不同，值会有字符串和数值两种类型。
- type 自定义事件的类型。根据不同的业务上报逻辑，我们将自定义事件分成如下4种类型：计数（count）、计算（calculate）、字符串属性（string property）和数值属性（numeric property）。每个类型的详细解释如下：
计数和计算类型的事件，除了上述属性之外，还可以增加事件参数（参见API说明部分）。
- 事件参数可以以更丰富的维度展示与该事件相关的数据。比如，游戏应用中的一种消费行为，开发者对发生该事件的用户性别，等级，年龄等感兴趣，就可以将性别，年龄，等级均设置为消费事件的参数；这样，对于该消费事件，除了统计发生次数外，还会展示事件发生时，用户的性别，年龄和等级的分布情况。
- 每个自定义事件最多可以传10个不同的参数。
3.6.1. 计数类型
计数类型事件通常用来描述一个事件累积发生的次数，适用的场景如按钮点击、界面进入、用户输入等。这类事件的上报代码如下：
[MiStatSDK recordCountEvent:@"button_click"];
[MiStatSDK recordCountEvent:@"button_click" dictionary:nil];
每次调用需要传入分类和主键，这类事件的value都隐式的被设置成数字“1”，不需要单独设置。统计后台会对这类事件做总发生次数、总覆盖用户数等统计计算。
3.6.2. 计算类型
计算类型事件通常用来描述一个带数值的事件的发生，适用的场景如用户消费事件，附带的数值是每次消费的金额；下载文件事件，附带的数值是每次下载消耗的时长等。这类事件的上报代码如下：
[MiStatSDK recordCalculateEvent:@"buy_book" value:8];
[MiStatSDK recordCalculateEvent:@"buy_book" value:8 dictionary:nil];
每次调用需要传入分类、主键和对应数值，其中数值是一个long型的整数。统计后台会对这类事件做累加、分布、按次平均、按人平均等统计计算。
3.6.3. 字符串属性类型
字符串属性类型通常用来描述某个具备字符串特征的属性，适用的场景如用户性别、用户职业、用户爱好等，这类属性的取值是一个字符串值。这类事件的上报代码如下：
[MiStatSDK recordPropertyEvent:@"user_profile" string:@"girl"];
每次调用需要传入分类、主键和字符串值。对于同一主键的字符串属性，一个设备只会保存一个，即，一个设备上报多次同一个主键的字符串属性类型，统计服务后台只会保存和统计最新的属性。
3.6.4. 数值属性类型
数值属性类型通常用来描述某个具备数值特征的属性，适用的场景如用户年龄、工作年限、游戏等级等，这类属性的取值是一个整型数值。这类事件的上报代码如下：
[MiStatSDK recordPropertyEvent:@"age" numeric:18];
每次调用需要传入分类、主键和数值。和字符串属性一样，对于同一主键的数值属性，一个设备只会保存一个，即，一个设备上报多次同一个主键的数值属性类型，统计服务后台只会保存和统计最新的属性。
3.7. 集成测试
我们提供了集成测试模块，通过简单的几个步骤，即可以观察到通过小米统计上传的数据，判断统计是否生效；集成测试的数据和正式数据完全隔离，互不干扰。具体步骤如下：
-
步骤一，增加测试设备。在统计数据网站中，点击进入“集成测试”项。通过在手机端调用[MiStatSDK getDeviceID]获取设备标示，增加到测试设备中。
图 1. 添加测试设备 -
步骤二，客户端上传统计数据，新增的测试设备统计数据会自动展示在测试日志列表中，点击可以查看该统计日志的详情。
图2.查看设备统计数据
图3.统计日志详情
4. 崩溃收集
应用程序发布后，在使用过程中，可能因为各种原因而崩溃。小米统计服务内置了崩溃日志上报功能。根据参数不同，开发者可以选择手动上传，或启动时上传崩溃日志，也可以选择和常规统计数据相同的上报策略。
日志收集的内容类似.crash文件，CallStack内容不是明文(内存地址)。所以，通过日志文件跟提交的dSYMs文件，需要进一步还原才能获得有效信息。
4.1. 初始化服务
当应用启动时候，需要调用统计SDK中的初始化方法。
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
[MiStatSDK enabledCrashReportWithMode:MI_STAT_CRASH_REPORTER_MODE_AUTO];
}
4.2. 崩溃上报策略
当有Crash发生时，SDK会把数据记录保存在本地。当app再次启动时，根据开发者设定的上报策略，触发上报流程。SDK中提供了一系列上报策略供开发者选择，这些策略包括：
-
MI_STAT_CRASH_REPORTER_MODE_AUTO 启动App时, 有Crash自动上报。
-
MI_STAT_CRASH_REPORTER_MODE_SYNC 遵循常规统计上报时机。
-
MI_STAT_CRASH_REPORTER_MODE_MANUAL 开发者处理上报时机。
本地只缓存最后一次Crash信息，如果数据上报成功，则会从本地删除。
设置上报策略的代码示例如下：
[MiStatSDK enabledCrashReportWithMode:MI_STAT_CRASH_REPORTER_MODE_AUTO];
手动上报策略的代码示例如下：
[MiStatCrashReporter enabledCrashReportWithMode:MI_STAT_CRASH_REPORTER_MODE_MANUAL];
if ([MiStatCrashReporter hasPendingCrashReport]) {
[MiStatCrashReporter triggerUploadCrashReport];
}
5. API说明
小米统计服务iOS版SDK所有的接口都以静态方法的形式封装在MiStatSDK这个类中。其中每个方法的详细描述如下：
5.1. + (void)registerMiStat:(NSString*)channel
初始化统计服务接口，必须在所有数据记录之前调用。推荐将该方法放入- (BOOL)application:(UIApplication )application didFinishLaunchingWithOptions:(NSDictionary )launchOptions 中。
表 2. initialize函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| channel | app的渠道信息，便于后台可按照渠道来统计应用的各项数据 |
5.2. + (void)setUploadPolicy:(UPLOAD_POLICY)policy interval:(int)interval
设置上报策略接口。
表 3. setUploadPolicy函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| policy | 所需要设置的上报策略类型，取值可从UPLOAD_POLICY_REALTIME、UPLOAD_POLICY_WIFI_ONLY、UPLOAD_POLICY_BATCH、UPLOAD_POLICY_WHILE_INITIALIZE、UPLOAD_POLICY_INTERVAL、UPLOAD_POLICY_DEVELOPMENT中选取 |
| interval （选填） | 时间间隔。当policy设置为UPLOAD_POLICY_INTERVAL的时候，该参数生效。 |
5.3. + (void)recordPage:(NSString*)name
记录界面进入事件，建议放在UIViewController 的- (void)viewDidAppear:(BOOL)animated方法中调用。
表 4. recordPageStart函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| name | 页面的名称 |
5.4. + (void)recordCountEvent:(NSString)category key:(NSString)key
记录自定义计数事件。
表 5. recordCountEvent函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| category | 事件的分类。 |
| key | 事件的主键，是这个自定义事件的唯一标识。 |
5.5. + (void)recordCountEvent:(NSString)category key:(NSString)key dictionary:(NSDictionary*)dictionary
记录自定义计数事件。并提供多关键字组合分析
表 6. recordCountEvent函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| category | 事件的分类。 |
| key | 事件的主键，是这个自定义事件的唯一标识。 |
| dictionary | 事件的参数，支持不超过10个不同的参数。 |
5.6. + (void)recordCalculateEvent:(NSString)category key:(NSString)key value:(long)value
记录自定义计算事件。
表 7. recordCalculateEvent函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| category | 事件的分类。 |
| key | 事件的主键，是这个自定义事件的唯一标识。 |
| value | 事件的值，是一个long型的整数。 |
5.7. + (void)recordCalculateEvent:(NSString)category key:(NSString)key value:(long)value dictionary:(NSDictionary*)dictionary
记录自定义计算事件。并提供多关键字组合分析
表 8. recordCalculateEvent函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| category | 事件的分类。 |
| key | 事件的主键，是这个自定义事件的唯一标识。 |
| value | 事件的值，是一个long型的整数。 |
| dictionary | 事件的参数，支持不超过10个不同的参数。 |
5.8. + (void)recordPropertyEvent:(NSString)category key:(NSString)key string:(NSString*)string
记录自定义字符串属性事件。
表 9. recordStringPropertyEvent函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| key | 事件的主键，是这个自定义事件的唯一标识。 |
| value | 事件的值，是一个字符串类型。 |
5.9. + (void)recordPropertyEvent:(NSString)category key:(NSString)key numeric:(long)numeric
记录自定义数值属性事件。
表 10. recordNumericPropertyEvent函数参数列表
| 参数列表 | 参数说明 |
|---|---|
| category | 事件的分类。 |
| key | 事件的主键，是这个自定义事件的唯一标识。 |
| value | 事件的值，是一个long型的整数。 |
5.10. + (void)triggerUploadManually;
手动触发上报，该调用仅会在当上报策略设置为UPLOAD_POLICY_DEVELOPMENT时起作用。
5.11. + (NSString*)getDeviceID;
获取设备标示。在接入SDK时, 通过此方法获取设备标示，添加到测试设备中，就可以在测试数据列表中看到该设备上报的统计数据。
5.12. + (void)enabledCrashReportWithMode:(MI_STAT_CRASH_REPORTER_MODE)mode;
开启崩溃日志收集功能。
表 11. 参数列表 |参数说明 ---|--- mode | 日志上报策略
5.13. + (BOOL)hasPendingCrashReport;
手动模式下, 用来检查本地是否有CrashReport。
5.14. + (void)triggerUploadCrashReport;
手动模式下, 触发上报CrashReport。成功后删除日志
This entry was posted in 技术文档 on 2014 年 9 月 4 日 by 吴, 青.