全部产品
云市场

移动数据分析

更新时间:2019-12-06 15:41:28

Mobile Analytics iOS SDK开发指南


1. 前言

本文档介绍了移动数据分析(Mobile Analytics) iOS SDK的使用方式。


Mobile Analytics iOS SDK是阿里云面向移动开发者提供的iOS平台下的数据统计与监控服务。通过该SDK,开发者可以在自己的APP中便捷地进行数据埋点,监控日常的业务数据与性能数据,并通过阿里云控制台界面观察对应的数据报表展现。另外,用户可以通过设定自定义的数据解析规则实现定制化的数据图表展现。

您可以通过获取alicloud-ios-demo工程源码获得移动数据分析服务的使用例程。


2. 安装Mobile Analytics iOS SDK

2.1 注意

  • 使用1.0.7及之前版本请在【Crash分析】板块查看crash信息。

  • 使用1.0.8版本及之后的版本,请在【新版Crash分析】板块查看crash信息。推荐使用1.0.8及之后的版本,crash数据更加准确,丢包率更小。

  • 删除- (ALBBMANTracker *)getTracker:(NSString) trackerId方法,请使用- (ALBBMANTracker *)getDefaultTracker代替。

  • 删除- (void)setCrashCaughtListener:(id<ALBBMANICrashCaughtListener>)aListener方法,1.0.8及之后的版本使用新的crash模块,无需再调用次方法设置参数。

2.2 手动集成SDK

将下载的包加至Link Binary With Libraries,包括:

  1. AlicloudMobileAnalytics.framework
  2. UTMini.framework
  3. UTDID.framework
  4. CrashReporter.framework

加载系统必须依赖的包:

  1. libz.tbd
  2. libresolv.tbd
  3. libsqlite3.tbd
  4. CoreTelephony.framework
  5. SystemConfiguration.framework

2.3 Pod集成

  • 指定Master仓库和阿里云仓库:
  1. source 'https://github.com/CocoaPods/Specs.git'
  2. source 'https://github.com/aliyun/aliyun-specs.git'
  • 添加依赖:
  1. pod 'AlicloudMAN', '~> 1.0.12'

(~>为模糊指定版本号方式,~> 1.0.12表明引用版本位于1.0.12 <= version < 1.1之间的最新版本SDK,用户可参考Podfile Syntax Reference,根据项目需要指定SDK版本。)

2.4 下载SDK统一配置文件

  • 在控制台产品概览页面,下载App的配置文件AliyunEmasServices-Info.plist,如下图所示:unit_config_pic

  • Xcode中,把下载的AliyunEmasServices-Info.plist文件拖入对应App Target下即可,在弹出框勾选Copy items if needed

  • 【附】AliyunEmasServices-Info.plist配置文件,包含SDK初始化所需的配置信息,用户只需要调用无需手动输入配置信息的autoInit初始化接口,参考第3节描述。

2.5 引用头文件

  1. #import <AlicloudMobileAnalitics/ALBBMAN.h>

特别说明:应用的targets->Build Settings->linking->Other Linker Flags,请加上-ObjC这个属性。

3. 获取Mobile Analytics服务

在您使用Mobile Analytics iOS SDK进行数据统计与监控前,您需要首先获取Mobile Analytics服务,然后可以进行版本和渠道的配置。

  • 手动输入配置信息,初始化接口:
  1. - (void)initWithAppKey:(NSString *)appKey secretKey:(NSString *)secretKey;
  • 自动初始化接口:
  1. - (void)autoInit;
  • MAN SDK初始化实例:
  1. // 获取MAN服务
  2. ALBBMANAnalytics *man = [ALBBMANAnalytics getInstance];
  3. // 打开调试日志,线上版本建议关闭
  4. // [man turnOnDebug];
  5. // 初始化MAN,无需输入配置信息
  6. [man autoInit];
  7. // appVersion默认从Info.list的CFBundleShortVersionString字段获取,如果没有指定,可在此调用setAppversion设定
  8. // 如果上述两个地方都没有设定,appVersion为"-"
  9. [man setAppVersion:@"2.3.1"];
  10. // 设置渠道(用以标记该app的分发渠道名称),如果不关心可以不设置即不调用该接口,渠道设置将影响控制台【渠道分析】栏目的报表展现。
  11. [man setChannel:@"50"];

4. 业务数据统计

数据统计的准确性依赖被监控APP的常规生命轨迹,比如应用启动次数依赖于用户正常退出应用触发的上报策略。

4.1 登录/注册会员

4.1.1 登录会员

接口:

  1. - (void)updateUserAccount:(NSString *)pNick userid:(NSString *)pUserId;

功能: 获取登录会员,然后会给每条日志添加登录会员字段

是否必须调用: 否

调用时机: 登录时调用

备注: 阿里云 平台上的登录会员 UV 指标依赖该接口

4.1.2 注册会员

接口:

  1. - (void)userRegister:(NSString *)pUsernick;

功能: 产生一条注册会员事件日志

是否必须调用: 否

调用时机: 注册时调用

备注: 阿里云 平台上注册会员指标依赖该接口

4.1.3 代码示例

  1. ALBBMANAnalytics *man = [ALBBMANAnalytics getInstance];
  2. [man userRegister:@"userNick"];
  3. [man updateUserAccount:@"userNick" userid:@"userId"];

完成上述埋点后,您就可以在阿里云控制台看到相应统计信息,例如下图显示实时统计里的登录会员和新注册会员。

user stastics

4.2 页面埋点

使用ALBBMANPageHitHelper可以进行ViewController级别的页面埋点,ALBBMANPageHitHelper为页面埋点辅助类,可以自动完成页面名称(默认获取ViewController名称并去除后缀Controller)、来源页面和页面停留时间的统计,如需使用更为灵活的页面埋点方案,可使用ALBBMANPageHitBuilder页面打点基础类进行页面埋点,详情见4.3节。

【注意】:如果App中没有进行页面埋点,活跃用户参数不能正常统计。

4.2.1 页面进入

接口:

  1. - (void)pageAppear:(UIViewController *)pViewController;

功能: 记录页面进入时的一些状态信息,但不发送日志,和 pageDisappear 配合使用

入参: UIViewController 或者其子类指针

是否必须调用; 需要对页面埋点时调用

调用时机: viewDidAppear

备注: 必须和 pageDisappear 搭配使用

4.2.2 页面离开

接口:

  1. - (void)pageDisAppear:(UIViewController *)pViewController;

功能: 页面离开发送页面事件日志,和 pageAppear 配合使用

入参: UIViewController 或者其子类指针

是否必须调用: 当调用了 pageAppear 后,必须调用 pageDisappear

调用时机: viewDidDisAppear

备注: 必须和 pageAppear 搭配使用

4.2.3 设置页面扩展参数

接口:

  1. - (void)updatePageProperties:(UIViewController *)pViewController properties:(NSDictionary *)pProperties;

功能:设置页面扩展参数

是否必须调用:否

调用时机:调用pageDisAppear之前

4.2.4 代码示例

  1. // 进入页面
  2. [[ALBBMANPageHitHelper getInstance] pageAppear:self];
  3. // 设置页面事件扩展参数
  4. NSDictionary *properties = [NSDictionary dictionaryWithObject:@"pageValue" forKey:@"pageKey"];
  5. [[ALBBMANPageHitHelper getInstance] updatePageProperties:self properties:properties];
  6. // 离开页面
  7. [[ALBBMANPageHitHelper getInstance] pageDisAppear:self];

4.3 页面事件

ALBBMANPageHitBuilder 类也是用来产生页面事件日志的,虽然 4.2 节中可以通过 pageAppear 和 pageDisAppear 来进行页面埋点,但是它针对的只是 UIViewController 级别的页面,并不能满足一些场景的页面事件,例如 UIView,如果用户需要将一个UIView 当做一个页面,那么就可以通过 ALBBMANPageHitBuilder 来进行页面事件的埋点,即用户自己采集页面事件相关的信息(如页面的 refer、页面停留时间等),通过 ALBBMANPageBuilder 构造出一条页面事件的日志 map,最后通过某个 ALBBMANTracker 埋点实例的 send API发送上传。

ALBBMANTracker是一个用于对埋点数据进行上报的工具,下文提到的ALBBMANPageHitBuilder等事件类都是通过ALBBMANTracker进行事件件上报的。其中ALBBMANTracker的获取如下所示:

  1. // 获取默认ALBBMANTracker实例
  2. ALBBMANTracker *tracker = [[ALBBMANAnalytics getInstance] getDefaultTracker];

埋点数据上报都是通过ALBBMANTracker进行,我们可以设定/删除上报数据的全局字段,全局字段设定后在所有的上报日志中都可以查看,如下所示:

  1. ALBBMANTracker *tracker = [[ALBBMANAnalytics getInstance] getDefaultTracker];
  2. // 设定全局字段
  3. [tracker setGlobalProperty:@"globalKey1" value:@"globalValue1"];
  4. // 删除全局字段
  5. [tracker removeGlobalProperty:@"globalKey1"];

4.3.1 设置页面名称

接口:

  1. - (void)setPageName:(NSString *)pPageName;

功能: 设置页面名称

入参: 页面名称,pPageName不能为空

是否必须调用: 是,在已经创建了 ALBBMANPageHitBuilder 实例后,必须调用该方法

调用时机: 创建 ALBBMANPageHitBuilder 后,必须调用 setPageName,否则调用 build 后返回为 nil

备注: 页面名称是页面事件的基础,必须设置

4.3.2 设置页面 refer

接口:

  1. - (void)setReferPage:(NSString *)pReferPageName;

功能: 设置页面的 refer,即当前页面的来源页面

入参: refer 页面名称,需要在 setPageName 的 PageName 集合中,也可以为空

是否必须调用: 否

4.3.3 设置页面停留时间

接口:

  1. - (void)setDurationOnPage:(long long)durationTimeOnPage;

功能: 记录页面从展现到页面离开的停留时间

入参: 页面停留时间

是否必须调用 否

调用时机: 需要记录当前页面停留时间

4.3.4 设置页面事件扩展参数

接口:

  1. - (void)setProperty:(NSString *)pKey value:(NSString *)pValue;

功能:给单条日志添加一个扩展参数

入参:key 和 value 都不能为 nil,其中 key 不能为PAGE/EVENTID/ARG1/ARG2/ARG3/ARGS,否则 build 返回 nil

是否必须调用:否

调用时机:需要给ALBBMANPageHitBuilder实例添加扩展参数时

4.3.5 组装单条日志 map

接口:

  1. - (NSDictionary *)build;

功能: 将塞入的参数组成 map 返回

入参: 无

是否必须调用: 否

调用时机: 创建 ALBBMANPageHitBuilder 或者 ALBBMANCustomHitBuilder 实例,塞入一些业务字段后,调用 build 组装业务字段生成日志 map,通过某个 ALBBMANTracker 埋点实例 send 接口发送

备注: build 函数返回的日志 map,必须通过ALBBMANTracker埋点上报工具的send接口上传数据完成打点

4.3.6 代码示例

  1. ALBBMANPageHitBuilder *pageHitBuilder = [[ALBBMANPageHitBuilder alloc] init];
  2. // 设置页面refer
  3. [pageHitBuilder setReferPage:@"pageRefer"];
  4. // 设置页面名称
  5. [pageHitBuilder setPageName:@"pageName"];
  6. // 设置页面停留时间
  7. [pageHitBuilder setDurationOnPage:100];
  8. // 设置页面事件扩展参数
  9. [pageHitBuilder setProperty:@"pagePropertyKey1" value:@"pagePropertyValue1"];
  10. [pageHitBuilder setProperty:@"pagePropertyKey2" value:@"pagePropertyValue2"];
  11. ALBBMANTracker *tracker = [[ALBBMANAnalytics getInstance] getDefaultTracker];
  12. // 组装日志并发送
  13. [tracker send:[pageHitBuilder build]];

上述的页面埋点与页面事件将影响控制台【页面路径分析】、【关键漏斗】、【控件点击】、【页面留存】等指标的报表展现,页面路径如下图所示。

page path


5. 自定义事件

自定义事件埋点可用于满足用户的定制化需求。

5.1 设置自定义事件的标签

接口:

  1. - (void)setEventLabel:(NSString *)pEventId;

功能: 区分不同自定义事件的标签,同一种自定义事件的 pEventId 相同

入参: 自定义事件标签,相当于自定义事件的业务 ID,不能为空,只能为字母、数字和下划线组成

是否必须调用: 是

调用时机: 创建 ALBBMANCustomHitBuilder 后,必须调用 setEventLabel,否则调用 build 后返回为 nil

备注: 对于自定义事件,必须设置标签,pEventId需要事先在wdm上申请

5.2 设置自定义事件的页面名称

接口:

  1. - (void)setEventPage:(NSString *)pPageName;

功能: 设置该自定义事件发生在哪个页面

入参: 自定义事件的页面名称,可以为空,这种情况日志中默认页面名称为 “UT”

是否必须调用: 否

调用时机: 需要明确该自定义事件发生时的页面,不调用情况下默认为 “UT”

5.3 设置自定义事件停留时间

接口:

  1. - (void)setDurationOnEvent:(long long)durationOnEvent;

功能: 设置自定义事件持续时间,跟 ALBBMANPageHitBuilder 中的页面停留时间类似

入参: 自定义事件停留时间

是否必须调用: 否

调用时机: 需要记录自定义事件的停留时间

5.4 设置自定义事件扩展参数

接口:

  1. - (void)setProperty:(NSString *)pKey value:(NSString *)pValue;

功能:给单条日志添加一个扩展参数

入参:key 和 value 都不能为 nil,其中 key 不能为PAGE/EVENTID/ARG1/ARG2/ARG3/ARGS,否则 build 返回 nil

是否必须调用:否

调用时机:需要给ALBBMANCustomHitBuilder实例添加扩展参数时

5.5 代码示例

  1. ALBBMANCustomHitBuilder *customBuilder = [[ALBBMANCustomHitBuilder alloc] init];
  2. // 设置自定义事件标签
  3. [customBuilder setEventLabel:@"test_event_label"];
  4. // 设置自定义事件页面名称
  5. [customBuilder setEventPage:@"test_Page"];
  6. // 设置自定义事件持续时间
  7. [customBuilder setDurationOnEvent:12345];
  8. // 设置自定义事件扩展参数
  9. [customBuilder setProperty:@"ckey0" value:@"value0"];
  10. [customBuilder setProperty:@"ckey1" value:@"value1"];
  11. [customBuilder setProperty:@"ckey2" value:@"value2"];
  12. ALBBMANTracker *traker = [[ALBBMANAnalytics getInstance] getDefaultTracker];
  13. // 组装日志并发送
  14. NSDictionary *dic = [customBuilder build];
  15. [traker send:dic];

自定义事件扩展参数在控制台【自定义事件】-【详细数据】-【参数分析】中可查看,但查看之前请在【管理设置】-【自定义事件管理】中添加要在控制台显示的事件ID。 如果您需要对自定义事件进行实时监控,请参考【5.3 自定义性能事件】章节。

6. 如何实时验证数据是否正常上报

您当前可以通过以下两种方式进行验证:

  • 打开移动数据分析log,查看是否会出现如***** UTMCEngine <info> ***** UTMCUploader:upload :: upload response:{"t":1464532326870,"ret":"","success":"success"}的日志;

    注意:SDK的日志上报会有缓存和聚合,因此上报时机会比API调用时机滞后一些,可耐心等待30-60s或将应用切到后台查看。

  • 登录控制台查看活跃用户等实时报表;

    注意:活跃用户的统计依赖页面埋点,移动数据分析后台会将零星的页面埋点处理为噪点,进行过滤,因此请确保您有足量的页面埋点事件上报(>5),另外控制台的实时报表大概会有5min的延迟。

7. H5页面数据的采集

H5页面采集并没有单独的SDK,依赖native进行上传,通过JSBridge通知给native,然后调用MAN的相应方法,进行数据的上报。可运行demo请参考:alicloud-ios-demo

7.1 代码示例

H5进行自定义事件的上报:

JavaScript代码:

  1. // 通过iframe发起请求,然后在native端进行捕获。
  2. var iframe = document.createElement("IFRAME");
  3. // 通过自定义scheme,来判断是正常请求还是H5通信。
  4. // 参数可以放在url中,然后在native解析。
  5. iframe.setAttribute("src", "jsbridge://custom");
  6. document.documentElement.appendChild(iframe);
  7. iframe.parentNode.removeChild(iframe);
  8. iframe = null;

Objective-c

  1. - (BOOL) webView:(UIWebView *)webView
  2. shouldStartLoadWithRequest:(NSURLRequest *)request
  3. navigationType:(UIWebViewNavigationType)navigationType
  4. {
  5. NSURL *url = [request URL];
  6. NSString *scheme = [url scheme];
  7. // js通信
  8. if ( [@"jsbridge" isEqualToString:scheme] ) {
  9. if ( [@"custom" isEqualToString:url.host] ) {
  10. ALBBMANCustomHitBuilder *customBuilder = [[ALBBMANCustomHitBuilder alloc] init];
  11. // 设置自定义事件标签
  12. [customBuilder setEventLabel:@"test_event_label"];
  13. // 设置自定义事件页面名称
  14. [customBuilder setEventPage:@"test_Page"];
  15. // 设置自定义事件持续时间
  16. [customBuilder setDurationOnEvent:12345];
  17. // 设置自定义事件扩展参数
  18. [customBuilder setProperty:@"ckey0" value:@"value0"];
  19. [customBuilder setProperty:@"ckey1" value:@"value1"];
  20. [customBuilder setProperty:@"ckey2" value:@"value2"];
  21. ALBBMANTracker *traker = [[ALBBMANAnalytics getInstance] getDefaultTracker];
  22. // 组装日志并发送
  23. NSDictionary *dic = [customBuilder build];
  24. [traker send:dic];
  25. }
  26. return NO;
  27. }
  28. return YES;
  29. }