小米统计服务iOS客户端SDK使用指南

目录

1. 客户端SDK功能概述
2. SDK集成说明
2.1. 搭建XCode运行环境
2.2. 配置SDK运行参数
3. 常规数据统计
3.1. 初始化统计服务
3.2. 数据上报策略
3.3. 默认事件
3.4. session
3.5. 页面访问
3.6. 自定义事件
3.7. 集成测试
4. 崩溃收集
4.1. 初始化服务
4.2. 崩溃上报策略
5. 网络请求
5.1. 初始化服务
5.2. 收集请求描述
6. API说明
6.1. + (void)registerMiStat:(NSString*)channel
6.2. + (void)setUploadPolicy:(UPLOAD_POLICY)policy interval:(int)interval
6.3. + (void)recordPage:(NSString*)name
6.4. + (void)recordCountEvent:(NSString*)category key:(NSString*)key
6.5. + (void)recordCountEvent:(NSString*)category key:(NSString*)key dictionary:(NSDictionary*)dictionary
6.6. + (void)recordCalculateEvent:(NSString*)category key:(NSString*)key
value:(long)value
6.7. + (void)recordCalculateEvent:(NSString*)category key:(NSString*)key
value:(long)value dictionary:(NSDictionary*)dictionary
6.8. + (void)recordPropertyEvent:(NSString*)category key:(NSString*)key
string:(NSString*)string
6.9. + (void)recordPropertyEvent:(NSString*)category key:(NSString*)key
numeric:(long)numeric
6.10. + (void)triggerUploadManually;
6.11. + (NSString*)getDeviceID;
6.12. + (void)enabledCrashReportWithMode:(MI_STAT_CRASH_REPORTER_MODE)mode;
6.13. + (BOOL)hasPendingCrashReport;
6.14. + (void)triggerUploadCrashReport;
6.15. + (void)enableAnalyticsNetwork:(id<MiAAnalyticsNetworkDelegate>)delegate;
6.16. – (NSString*)mistatAnalyticsNetwork:(NSString*)url;

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的活跃度、打开频率、使用时长等)、页面访问统计和自定义事件统计。

统计服务提供app的崩溃日志收集功能。功能开启后,对于app在使用过程中的崩溃,SDK将自动采集崩溃日志,并上传到统计后台;统计后台会根据app版本,对崩溃进行聚合、展示。开发者可以根据app实际情况情况,将该崩溃标记成已处理或者忽略状态。

统计服务提供app的网络使用情况的收集。开启后可以对基于NSURL的所有请求进行记录,并上传到统计后台;后台分请求数,时长,错误等进行聚合,展示。

2. SDK集成说明

本节主要介绍如何配置和使用小米统计SDK,开发者也可以参照SDK中的demo来配置和使用小米统计SDK。

2.1. 搭建XCode运行环境

我们的libMiStatSDK库文件同时包含i386、armv6和armv7的代码,所以libMiStatSDK将同时支持真机与模拟器。

  1. 小米统计服务iOS版支持的最低系统版本iOS4.3
  2. 添加libMiStatSDK.a , MiStatSDK.h,MiStatCrashReporter.h,MiStatNetwork.h 到工程
  3. 引入库 libz.dylib,SystemConfiguration.framework,MobileCoreServices.framework
    (如果已经引入,请忽略)

2.2. 配置SDK运行参数

运行SDK注册小米统计服务的时候,需要使用AppId,AppKey,等参数来验证使用者的合法性。

  1. 打开工程下资源文件Info.plist
  2. 文件为源代码形式打开,添加以下信息
    <dict>
    	<key>MiSDKAppID</key>
    	<string>1000888</string>
    	<key>MiSDKAppKey</key>
    	<string>500088888888</string>
    </dict>
  3. 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会将该事件放入默认&#303#30340;类别中。
  • 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. 网络请求

app在运行期间,基于NSURL的请求都会被收集到。

5.1. 初始化服务

当应用启动时候,需要调用初始化方法。

如果希望对url地址信息进行筛选或过略,可以实现对应delegate,并返回相应url字符串即可。返回的url才是真正上报的内容。

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [MiStatNetwork enableAnalyticsNetwork:self];
}

#pragma mark - MiAAnalyticsNetworkDelegate
- (NSString*)mistatAnalyticsNetwork:(NSString*)url
{
    return url;
}

5.2. 收集请求描述

根据object-c
网络Framework描述,收集使用NSURLProtocol方式。所以我们只能收集基于WebKit,NSURL之上的网络请求。CFNetWork,CFStream,CFSocket无法收集。

6. API说明

小米统计服务iOS版SDK所有的接口都以静态方法的形式封装在MiStatSDK这个类中。其中每个方法的详细描述如下:

6.1. + (void)registerMiStat:(NSString*)channel

初始化统计服务接口,必须在所有数据记录之前调用。推荐将该方法放入- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 中。

表 2. 

参数列表 参数说明
channel app的渠道信息,便于后台可按照渠道来统计应用的各项数据

 

6.2. + (void)setUploadPolicy:(UPLOAD_POLICY)policy interval:(int)interval

设置上报策略接口。

表 3. 

参数列表 参数说明
policy 所需要设置的上报策略类型, UPLOAD_POLICY_TYPE_LAUNCH 启动时发送 UPLOAD_POLICY_TYPE_REALTIME
实时发送 UPLOAD_POLICY_TYPE_WIFI_ONLY 只在wifi下, 时时 UPLOAD_POLICY_TYPE_INTERVAL 间隔时间
UPLOAD_POLICY_TYPE_DEVELOPMENT 开发者模式
interval (选填) 时间间隔。当policy设置为UPLOAD_POLICY_TYPE_INTERVAL的时候,该参数生效。

 

6.3. + (void)recordPage:(NSString*)name

记录界面进入事件,建议放在UIViewController 的- (void)viewDidAppear:(BOOL)animated方法中调用。

表 4. 

参数列表 参数说明
name 页面的名称

 

6.4. + (void)recordCountEvent:(NSString*)category key:(NSString*)key

记录自定义计数事件。

表 5. 

参数列表 参数说明
category 事件的分类。
key 事件的主键,是这个自定义事件的唯一标识。

 

6.5. + (void)recordCountEvent:(NSString*)category key:(NSString*)key dictionary:(NSDictionary*)dictionary

记录自定义计数事件。并提供多关键字组合分析

表 6. 

参数列表 参数说明
category 事件的分类。
key 事件的主键,是这个自定义事件的唯一标识。
dictionary 方便对事件进行更多维度的分析。其中参数值不支持数值,支持不超过10个不同的参数

 

6.6. + (void)recordCalculateEvent:(NSString*)category key:(NSString*)key
value:(long)value

记录自定义计算事件。

表 7. 

参数列表 参数说明
category 事件的分类。
key 事件的主键,是这个自定义事件的唯一标识。
value 事件的值,是一个long型的整数。

 

6.7. + (void)recordCalculateEvent:(NSString*)category key:(NSString*)key
value:(long)value dictionary:(NSDictionary*)dictionary

记录自定义计算事件。并提供多关键字组合分析

表 8. 

参数列表 参数说明
category 事件的分类。
key 事件的主键,是这个自定义事件的唯一标识。
value 事件的值,是一个long型的整数。
dictionary 方便对事件进行更多维度的分析。其中参数值不支持数值,支持不超过10个不同的参数

 

6.8. + (void)recordPropertyEvent:(NSString*)category key:(NSString*)key
string:(NSString*)string

记录自定义字符串属性事件。

表 9. 

参数列表 参数说明
category 事件的分类。
key 事件的主键,是这个自定义事件的唯一标识。
value 事件的值,是一个字符串类型。

 

6.9. + (void)recordPropertyEvent:(NSString*)category key:(NSString*)key
numeric:(long)numeric

记录自定义数值属性事件。

表 10. 

参数列表 参数说明
category 事件的分类。
key 事件的主键,是这个自定义事件的唯一标识。
value 事件的值,是一个long型的整数。

 

6.10. + (void)triggerUploadManually;

手动触发上报,该调用仅会在当上报策略设置为UPLOAD_POLICY_DEVELOPMENT时起作用。

6.11. + (NSString*)getDeviceID;

获取设备标示。在接入SDK时, 通过此方法获取设备标示,添加到测试设备中,就可以在测试数据列表中看到该设备上报的统计数据。

6.12. + (void)enabledCrashReportWithMode:(MI_STAT_CRASH_REPORTER_MODE)mode;

开启崩溃日志收集功能。

表 11. 

参数列表 参数说明
mode 日志上报策略。

 

6.13. + (BOOL)hasPendingCrashReport;

手动模式下, 用来检查本地是否有CrashReport。

6.14. + (void)triggerUploadCrashReport;

手动模式下, 触发上报CrashReport。成功后删除日志

6.15. + (void)enableAnalyticsNetwork:(id<MiAAnalyticsNetworkDelegate>)delegate;

网络请求统计, 包括URL, 请求时长,错误码等信息

表 12. 

参数列表 参数说明
delegate id<MiAAnalyticsNetworkDelegate> 可以根据你的需求 定制统计url的内容. 或则对此次请求忽略.
nil为忽略.

 

6.16. - (NSString*)mistatAnalyticsNetwork:(NSString*)url;

可以根据你的需求 定制统计url的内容. 或则对此次请求忽略

表 13. 

参数列表 参数说明
url 监听到的网络请求原地址