全部产品
云市场

iOS接入

更新时间:2018-08-28 17:53:49

1. SDK集成

  • 指定SDK CocoaPods仓库:
  1. source 'git@gitlab-ce.emas-poc.com:EMAS-iOS/emas-specs.git'
  • 添加SDK依赖:
  1. pod 'EMASMAN', '10.0.0'
  2. pod 'UserTrack', '6.3.5.100005-poc'
  3. pod 'Reachability', '3.2'
  4. pod 'FMDB', '2.7.2'
  • 工程引入头文件:
  1. #import <EMASMAN/EMASMAN.h>
  2. #import <TBRest/TBRestConfiguration.h>
  3. #import <TBRest/TBRestSendService.h>
  4. #import <UT/UTAnalytics.h>
  5. #import <UT/AppMonitor.h>

2. SDK使用

2.1 SDK初始化

  • 填入appKeyappSecret初始化数据分析SDK。
  • 调用该接口初始化SDK前,需要先初始化UTAnalytics,并完成上报配置TBRestConfiguration;该部分配置和EMAS高可用共用,可参考文档:EMAS iOS SDK快速集成,查看对应配置项含义,也可以参考下面的示例代码。
  1. - (void)initWithAppKey:(NSString *)appKey appSecret:(NSString *)appSecret;
  • 示例代码
  1. @property (nonatomic, strong) EMASMANService *manService;
  2. // appKey/appSecret从EMAS控制台获取应用信息
  3. NSString *appKey = @"xxx";
  4. NSString *appSecret = @"xxx";
  5. NSString *uploadHost = @"xxx";
  6. NSString *timestampHost = @"xxx";
  7. NSString *scheme = @"https";
  8. // 打开调试日志
  9. [[UTAnalytics getInstance] turnOnDebug];
  10. // 设置埋点上报协议:http/https
  11. [[UTAnalytics getInstance] setTimestampHost:timestampHost scheme:scheme];
  12. [[UTAnalytics getInstance] setAppKey:appKey secret:appSecret];
  13. // 调试使用,上报不采样,建议正式发布版本不要这么做
  14. [AppMonitor disableSample];
  15. // 上报配置
  16. TBRestConfiguration *restConfiguration = [[TBRestConfiguration alloc] init];
  17. restConfiguration.appkey = appKey;
  18. restConfiguration.dataUploadScheme = scheme;
  19. restConfiguration.dataUploadHost = uploadHost;
  20. [[TBRestSendService shareInstance] configBasicParamWithTBConfiguration:restConfiguration];
  21. _manService = [EMASMANService sharedInstance];
  22. [_manService initWithAppKey:appKey appSecret:appSecret];

2.2 日志开关

  • 打开/关闭日志,默认是关闭。
  1. - (void)enableLog:(BOOL)enable;
  • 示例代码:
  1. [_manService enableLog:true];

2.3 App版本号

  • 设置App版本号。
  1. - (void)setAppVersion:(NSString *)appVersion;
  • 示例代码:
  1. [_manService setAppVersion:@"1.1.1"];

2.4 App渠道

  • 设置App渠道。
  1. - (void)setChannel:(NSString *)channel;
  • 示例代码:
  1. [_manService setChannel:@"aliyun"];

2.5 用户注册

  • 用户注册。
  1. - (void)userRegister:(NSString *)userNick;
  • 示例代码:
  1. [_manService userRegister:@"testUserNick"];

2.6 用户登录

  • 用户登录。
    • userNick对应2.5节用户注册的用户名;
    • userId为用户名对应的ID。
  1. - (void)userLogin:(NSString *)userNick userId:(NSString *)userId;
  • 示例代码:
  1. [_manService userLogin:@"testUserNick" userId:@"testUserId"];

2.7 上报日志数据

  • 上报日志数据。
  1. - (void)send:(NSDictionary *)logDic;
  • 示例代码:
  1. // 上报页面基础埋点
  2. EMASMANPageHitBuilder *pageHitBuilder = [[EMASMANPageHitBuilder alloc] init];
  3. [pageHitBuilder setPageName:@"testPage"];
  4. ...
  5. [pageHitBuilder setProperty:@"pageKey1" value:@"pageValue1"];
  6. [_manService send:[pageHitBuilder build]];
  7. // 上报自定义事件埋点
  8. EMASMANCustomHitBuilder *customHitBuilder = [[EMASMANCustomHitBuilder alloc] init];
  9. [customHitBuilder setEventLabel:@"testEventLable"];
  10. ...
  11. [customHitBuilder setProperty:@"key1" value:@"value1"];
  12. [_manService send:[customHitBuilder build]];

2.8 页面辅助埋点

使用EMASMANPageHitHelper可以进行ViewController级别的页面埋点,可自动完成页面名称(默认获取ViewController名称,并去除后缀Controller)、来源页面和页面停留事件的统计上报。如需使用更为灵活的页面埋点方案,可使用EMASMANPageHitBuilder页面基础埋点,详情见2.7节。

  • 页面进入:
    • 进入页面时调用,不会触发日志上报;
    • 调用时机:ViewController生命周期viewDidAppear
    • 需要配合pageDisAppear使用。
  1. - (void)pageAppear:(UIViewController *)viewController;
  • 页面离开:
    • 离开页面时调用,触发日志上报;
    • 调用时机:ViewController生命周期viewDidDisAppear
    • 需要配合pageAppear使用。
  1. - (void)pageDisAppear:(UIViewController *)viewController;
  • 设置页面扩展参数:
    • 设置页面扩展参数;
    • 调用时机:调用pageDisAppear前;
    • 非必须调用。
  1. - (void)updatPage:(UIViewController *)viewController properties:(NSDictionary *)properties;

示例代码:

  1. // 基础类BaseUIViewController
  2. @interface BaseUIViewController ()
  3. @end
  4. @implementation BaseUIViewController
  5. - (void)viewDidLoad {
  6. [super viewDidLoad];
  7. }
  8. - (void)viewDidAppear:(BOOL)animated {
  9. [[EMASMANPageHitHelper sharedInstance] pageAppear:self];
  10. }
  11. - (void)viewDidDisappear:(BOOL)animated {
  12. [[EMASMANPageHitHelper sharedInstance] pageDisAppear:self];
  13. }
  14. - (void)didReceiveMemoryWarning {
  15. [super didReceiveMemoryWarning];
  16. }
  17. @end
  18. // TestUIViewController继承自BaseUIViewController
  19. @interface TestUIViewController ()
  20. @end
  21. @implementation TestUIViewController
  22. - (void)viewDidLoad {
  23. [super viewDidLoad];
  24. // 设置页面扩展参数
  25. NSDictionary *pageProperties = @{ @"pageKey":@"pageValue" };
  26. [[EMASMANPageHitHelper sharedInstance] updatPage:self properties:pageProperties];
  27. }
  28. @end

2.9 页面基础埋点

2.6节所述的EMASMANPageHitHelper只适用于UIViewController级别的页面,其不能满足一些场景的页面事件,比如:UIView等。EMASMANPageHitBuilder为页面基础埋点构建类,用户可自行采集页面事件相关信息,比如:来源页面、页面停留时间等,最后构造出页面事件的日志,最终通过调用日志上报接口。

  • 设置页面名:
    • 设置页面名称,pageName为非空;
    • 页面名称是页面事件的基础,必须设置。
  1. - (void)setPageName:(NSString *)pageName;
  • 设置来源页面名:
    • 设置当前页面的来源页面。
  1. - (void)setReferPage:(NSString *)referPageName;
  • 设置页面停留时间:
    • 记录从进入到离开页面的停留时间,单位:毫秒。
  1. - (void)setDurationOnPage:(long long)duration;
  • 设置页面扩展参数:
    • 添加页面扩展参数,其中key不能为PAGE/EVENTID/ARG1/ARG2/ARG3/ARGS
  1. - (void)setProperty:(NSString *)key value:(NSString *)value;
  2. - (void)setProperties:(NSDictionary *)pageProperties;
  • 页面日志构建:
    • 构建生成页面埋点日志,可调用2.7节日志上报接口将其上报。
  1. - (NSDictionary *)build;
  • 示例代码:
  1. EMASMANPageHitBuilder *pageHitBuilder = [[EMASMANPageHitBuilder alloc] init];
  2. [pageHitBuilder setPageName:@"testPage"];
  3. [pageHitBuilder setReferPage:@"testReferPage"];
  4. [pageHitBuilder setDurationOnPage:1000];
  5. [pageHitBuilder setProperty:@"pageKey1" value:@"pageValue1"];
  6. [pageHitBuilder setProperty:@"pageKey2" value:@"pageValue2"];
  7. [pageHitBuilder setProperties:@{ @"pageKey3" : @"pageValue3" }];
  8. [_manService send:[pageHitBuilder build]];

2.10 自定义事件埋点

  • 设置标签:
    • 设置自定义事件标签;
    • 用于区分唯一标识自定义事件,必须设置。
  1. - (void)setEventLabel:(NSString *)eventLabel;
  • 设置页面名:
    • 标识自定义事件发生的页面;
    • 非必须调用。
  1. - (void)setEventPage:(NSString *)page;
  • 设置事件停留时间:
    • 自定义事件持续时间。
  1. - (void)setDurationOnEvent:(long long)duration;
  • 设置扩展参数:
    • 自定义事件扩展参数设置,其中key不能为PAGE/EVENTID/ARG1/ARG2/ARG3/ARGS
  1. - (void)setProperty:(NSString *)key value:(NSString *)value;
  2. - (void)setProperties:(NSDictionary *)properties;
  • 自定义事件日志构建:
    • 构建生成自定义事件埋点日志,可调用2.5节日志上报接口将其上报。
  1. - (NSDictionary *)build;

示例代码:

  1. EMASMANCustomHitBuilder *customHitBuilder = [[EMASMANCustomHitBuilder alloc] init];
  2. [customHitBuilder setEventLabel:@"testEventLable"];
  3. [customHitBuilder setEventPage:@"testEventPage"];
  4. [customHitBuilder setDurationOnEvent:1234];
  5. [customHitBuilder setProperty:@"key1" value:@"value1"];
  6. [customHitBuilder setProperty:@"key2" value:@"value2"];
  7. [customHitBuilder setProperty:@"key3" value:@"value3"];
  8. [customHitBuilder setProperties:@{ @"key4" : @"value4" }];
  9. [_manService send:[customHitBuilder build]];

3. 调试验证

SDK集成测试时,如何验证数据是否正确上报,可参照下述步骤执行。

3.1 打开调试日志

  • 调用SDK接口,打开调试日志。
  1. [_manService enableLog:true];
  • SDK正确初始化后,可看到类似日志:
  1. 2018-06-24 19:50:09.287006+0800 EMASMANTestApp[10240:593381] [UT][DEBUG]-[UTMCUploadManager setInterval:] line:158
  2. 设置上传时间间隔: 27
  3. =================================================
  4. 2018-06-24 19:50:09.287223+0800 EMASMANTestApp[10240:593381] [UT][DEBUG]-[UTMCUploadManager start] line:108
  5. 开始上传
  6. =================================================
  7. 2018-06-24 19:50:09.287381+0800 EMASMANTestApp[10240:593381] [UT][DEBUG]-[UTMCUploadManager startWithMode:] line:277
  8. 开启默认上传模式

3.2 埋点事件上报

  • 参照第2节,选择一事件上报,例:上报自定义事件,
  1. EMASMANCustomHitBuilder *customHitBuilder = [[EMASMANCustomHitBuilder alloc] init];
  2. [customHitBuilder setEventLabel:@"testEventLable"];
  3. [customHitBuilder setEventPage:@"testEventPage"];
  4. [customHitBuilder setDurationOnEvent:1234];
  5. [customHitBuilder setProperty:@"key1" value:@"value1"];
  6. [customHitBuilder setProperty:@"key2" value:@"value2"];
  7. [customHitBuilder setProperty:@"key3" value:@"value3"];
  8. [customHitBuilder setProperties:@{ @"key4" : @"value4" }];
  9. [_manService send:[customHitBuilder build]];
  • 若看到如下类似日志,说明埋点成功:
  1. 2018-06-24 19:55:55.059505+0800 EMASMANTestApp[10240:594124] [UT][INFO]+[UTMCLogAssemble map2String:] line:361
  2. The original log format:
  3. 1886784664df973c7f9543fa7f77e1372fbfd3cb||-||Apple||x86_64||2436*1125||Unknown||WiFi||Unknown||aliyun||20000067||1.1.1||userNick-1529823865.023121||-||userNick-1529823865.023121||-||en||m||11.3||6.3.5||1529841009281||WsLWEjCJQ1oDAMjTOKxtNidv||mini||-||81000001||-||-||-||1529841355053||testEventPage||19999||testEventLable||-||1234||key2=value2,key3=value3,key1=value1,key4=value4
  4. =================================================

3.3 日志上报策略

  • App启动后尝试首次上报日志,之后按照定时间隔(30s)上报。
  • App切换到后台,立即上报。

3.4 日志上报验证

SDK内部有日志上报控制策略,埋点完成后不一定立即上报,可等待一段时间或者App进行几次前后台切换,触发日志上报。若可看到如下类似日志,说明日志上报成功:

  1. 2018-06-24 19:56:39.353127+0800 EMASMANTestApp[10240:594124] [UT][INFO]-[UTMCLogUploader _uploadThroughHttps:logs:] line:343
  2. 上传成功: {
  3. allLength = 25;
  4. dataLen = 17;
  5. errorcode = 0;
  6. flag = 40;
  7. recvData = "{\"config\":{}}";
  8. type = 2;
  9. version = 1;
  10. }
  11. 上传条数: 1