¶ iOS SDK 集成
¶ 1. 获取 SDK
¶ 1.下载SDK
- SDK 下载，解压后为 HMTAgentSDK.h
- 导入 SDK。在项目工程目录结构中，右键点击项目，选择 Add Files to "项目名称".. 来添加现有文件，选择解压后的 SDK 文件 (或者也可以直接将 HMTAgentSDK.h 文件拖拽至项目工程目录结构中)。记得勾选 Copy items if needed，点击 Finish 完成操作。
¶ 2.添加依赖框架
需要添加以下框架:
CoreFoundation.framework
CoreLocation.framework
CoreMotion.framework
CoreTelephony.framework
Security.framework
SystemConfiguration.framework
AdSupport.framework
libsqlite3.tbd
libz.1.1.3.tbd
¶ 2. 在 Xcode 的 buildsettings 增加配置
由于 iOS SDK 从 1.2.12 版本开始对页面交换的方法做了升级，若使用 1.2.12 及之后版本的 iOS SDK，且未关闭页面自动埋点，请在 Build Settings 中修改，确保 Other Linker Flags 参数包含"-ObjC"或"-all_load"：
¶ 基础功能
¶ 1、嵌入代码
在需要引用 SDK 的地方添加引用头文件：
#import "HMTAgentSDK.h"
Swift在briding header中引用头文件
@import HMTAgentSDK
¶ 2、初始化 SDK
在 AppDelegate.m 中的 didFinishLaunchingWithOptions 函数添加如下函数调用
*如需关闭自动布码，若开发者希望自已对每个页面进行手动的命名和采集，则在初始化SDK前调用
[HMTAgentSDK setViewHook:NO];
*如需需要修改服务器地址，在调用 initWithAppKey 初始化SDK方法前调用 setServerHost 方法
[HMTAgentSDK setServerHost:@"https://yourtracker.com"];
*如果需要修改配置文件服务器地址，在调用 initWithAppKey 初始化SDK方法前调用 setOnLineConfigUrl 方法
[HMTAgentSDK setOnLineConfigUrl:@"https://yourtracker.com"];
可根据需求,选择下面的初始化方法其中一种方法:
1.直接初始化方式(默认为启动时发送):
[HMTAgentSDK initWithAppKey:#appkey channel:#channel];
2.初始化带数据发送模式(如果首次读取配置失败,则按照此处发送模式发送):
[HMTAgentSDK initWithAppKey:#appkey channel:#channel reportPolicy:#reportPolicy];
3.初始化并设置指定参数黑名单(unTracked为不提交参数)
[HMTAgentSDK initWithAppKey:#appkey channel:#channel reportPolicy:#reportPolicy unTracked:@[@"#untracked1",@"#untracked2"]];
4.初始化并设置指定URL白名单(trackedUrl为白名单域名)
[HMTAgentSDK initWithAppKey:#appkey channel:#channel reportPolicy:#reportPolicy trackedUrl:@[@"#trackedUrl1",@"trackedUrl2"]];
5.初始化并设置指定参数黑名单(unTracked为不提交参数),设置指定URL白名单(trackedUrl为白名单域名)
[HMTAgentSDK initWithAppKey:#appkey channel:#channel reportPolicy:#reportPolicy unTracked:@[@"#untracked1",@"#untracked2"] trackedUrl:@[@"#trackedUrl1",@"trackedUrl2"]];
*如需通过SDK采集deeplink打开的链接用于后续分析，则请在在appdelegate的openurl方法中调用我们SDK即可，openurl方法有多个，
可以选择性布码，如：
[HMTAgentSDK routeHLink:url];
- 关于修改服务器地址，若您使用的是独立部署的环境，有可能配置了独立的 tracker，则上报地址和配置文件获取的地址都需要修改，请在初始化前通过 setServerHost、setOnLineConfigUrl 进行配置
- 初始化参数中，#appkey 即为准备工作中创建应用后获取的 AppKey ；#channel 为应用发布的渠道 ID，默认为 @"App Store"，若有其他渠道需要区分，则可传入自定义的值。（chennel 的命名规范详见渠道命名规范）
- 渠道的影响：在计算页面报告时，会通过 channel 参数区分不同渠道来源的日志，并以此计算渠道的细分数据。
- reportPolicy 参数目前支持两个值：HMT_REALTIME；HMT_BATCH。分别对应实时模式和启动时批量发送实时模式：每次的应用启动、页面切换、事件触发都会实时进行上报启动时批量发送：各类数据产生后，将会在下次启动时批量打包上报在 SDK 设置后，上报模式还可以在管理平台的项目信息页中进行变更，系统会下发新的配置文件使 SDK 获取新的模式
- unTracked 参数为黑名单参数数组，将需要过滤的参数填入其中，SDK 将不会发送该参数到服务器。trackedUrl 参数为 URL 白名单，将需要拦截的域名填入其中，当发生网络请求时，只有白名单设置过的域名下的 URL 数据会被发送到服务器。trackedUrl 参数中如果存在成员 @"*"，则发送全部 URL 数据。
至此，最基本的集成已完成，SDK 已支持自动采集上报应用的开启、页面切换。
¶ 3、自定义行为跟踪
除了基本的应用打开和页面访问的采集外，SDK 还支持自定义的事件的统计分析，例如可以上报某个按钮的点击事件。
SDK 提供了以下接口：
1.只有事件名称
[HMTAgentSDK postAction:@"#actName"];
2.只有事件名称，带回调处理
[HMTAgentSDK postAction:@"#actName" callback:#callback];
3.带次数
[HMTAgentSDK postAction:@"#actName" acc:1];
4.带次数，带回调处理
[HMTAgentSDK postAction:@"#actName" acc:1 callback:#callback];
5.带自定义属性，如：
NSDictionary *dict = @{
@"username" : @"Jone",
@"gender" : @"male",
@"habit" : @"sleep",
@"array":@[@"1",@"2",@"3"]
};
[HMTAgentSDK postAction:@"register" acc:1 property:dict];
6.带自定义属性，带回调处理，如：
NSDictionary *dict = @{
@"username" : @"Jone",
@"gender" : @"male",
@"habit" : @"sleep",
@"array":@[@"1",@"2",@"3"]
};
[HMTAgentSDK postAction:@"register" acc:1 property:dict callback:#callback];
¶ 应用场景
例如：一位用户将一个页面分享给了其他用户，首先定义 1 个行为名称叫: share，然后定义一个 3 个参数, name, url ，type
NSDictionary *dict = @{
@"name" : @"xiaoming",
@"url" : @"https://www.hypers.com/",
@"type" : @"微信",
};
[HMTAgentSDK postAction:@"share" acc:1 property:dict callback:#callback];
例如：一位刚考上大学的学生需要购买一些电子产品，因为下单的商品为多个，所以在传递时候可以采用数组类型。
NSDictionary *dict = @{
@"username" : @"xiaoming",
@"gender" : @"male",
@"total_price" : @"15000",
@"goods":@[
@{@"name":@"电脑",@"type":@"数码",@"price":@"18000",@"count":@"1"},
@{@"name":@"手机",@"type":@"数码",@"price":@"1000",@"count":@"3"},
]};
[HMTAgentSDK postAction:@"buy" acc:1 property:dict callback:#callback];
需要采集的自定义事件（#actName）和属性（property 字典中的 key）需要事先在管理平台中创建，分别位于设置-自定义事件和设置-自定义属性。否则未知的 actName 和属性 key 将会被计算平台过滤，从而不会体现在事件和属性的报告中
带次数的接口 3、4 表示一次上报某个事件多次的触发行为。如：直播视频中可以频繁点击的“赞”按钮，若每次点击都进行上报则请求会非常频繁，同时对带宽资源造成不必要的消耗。这种情况下，可以采用接口 3 和 4 的形式，每隔一段时间上报一次，统计用户这段时间内的点赞次数作为 acc 的值。
¶ 4、错误采集
SDK 支持对错误的采集上报，但为了避免开发者已使用其他的错误捕获而造成冲突，默认状态下开关为关闭，若需要打开，请进行如下设置：
[HMTAgentSDK setCrashReportEnabled:YES];
¶ 5、在 APP 端检查埋点
在初始化前调用（记得在发版前去掉）
[HMTAgentSDK openDebugView];
当有 SDK 的日志生成时，会有如下弹窗提示，信息包括日志类型和上报域名，可点击复制，将日志内容拷贝至外部查看，其中将包含更多明细的字段。
¶ 高级功能
¶ 发送自定义的页面
通过 SDK 自动布码抓取页面并不一定能满足全部业务需求，比如想要更改上报的页面名称时，可以使用自定义的页面布码。（如果仅想更改报表中展示的页面名称，可以在管理端中，通过设置-页面修改页面展示名称）
-(void)viewDidAppear:(BOOL)animated {[super viewDidAppear:animated];
//在每个 Activity 已经进入时调用
//方法1.页面开始
[HMTAgentSDK startTracPage:@"#activity"];
//方法2.页面开始,带处理完成回调
[HMTAgentSDK startTracPage:@"#activity" callback:^{
NSLog(@"进入页面处理完毕");
}];
}
//即将离开页面
- (void)viewWillDisappear:(BOOL)animated {
[super viewWillDisappear:animated];
//在每个Activity即将离开时调用
//方法1.页面结束
[HMTAgentSDK endTracPage];
//方法2.页面结束，带处理完成回调
[HMTAgentSDK endTracPage callback:^{
NSLog(@"结束页面处理完毕");
}];
}
在上述页面开始方法中，#activity 即为自定义的页面名称。
¶ 在页面中添加自定义属性
自定义属性一般是与自定义事件进行结合使用，但也可以加在页面的上报中，比如需要在上报某个页面的同时记录用户是否为会员，此时可以如下布码：
//已经进入页面
-(void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
//在每个 Activity 已经进入时调用
//方法1.页面开始
[HMTAgentSDK startTracPage:@"#activity"];
//方法2.页面开始,带处理完成回调
[HMTAgentSDK startTracPage:@"#activity" callback:^{
NSLog(@"进入页面处理完毕");
}];
}
//即将离开页面
- (void)viewWillDisappear:(BOOL)animated {
[super viewWillDisappear:animated];
//在每个Activity即将离开时调用,带自定义属性
NSDictionary *dict = @{
@"usertype" : @"member",
@"level" : @"golden",
};
[HMTAgentSDK endTracPage:dict];
//或者,带自定义属性,同时带处理完成回调
[HMTAgentSDK endTracPage:dict callback:^{
NSLog(@"离开页面处理完毕");
}];
}
···
以上dict中使用到的key也需要在设置-自定义属性中提前创建，同时也可以修改 `#activity` 自定义该页面的名称
¶ 在访问中一直携带某个属性
SDK 提供了临时和永久俩种类型的额外属性，开发者可以针对这俩种属性进行新增和移除操作
SDK 提供枚举类型 HMTCacheState 对属性类型进行设置：
- HMT_CacheTemporary 表示临时属性
- HMT_CachePermanent 表示永久属性
注意：
- 临时属性的优先级高于永久属性，俩者冲突时会选用临时属性
- 重复设置相同的属性，会对属性对应的值进行更新
临时属性
临时属性仅当次设置有效，其生命周期与当次 App 运行内存相同，App 重新打开需重新设置
永久属性:
永久属性会多次生效，直到 App 缓存被清除或永久属性被移除
¶ 设置属性
SDK 提供接口
+ (BOOL)bindUserDefineProperty:(NSDictionary *)porperty cacheState:(HMTCacheState)state;
来进行属性的新增操作
参数 property:传入所需属性字典，state:为属性为临时性或持久性枚举值
示例-设置一个本次访问期内有效的会员等级属性：
NSDictionary *dict = @{@"member_level" : @"normal"};
[HMTAgentSDK bindUserDefineProperty:dict cacheState:HMT_CacheTemporary];
¶ 移除属性
SDK 提供接口
+ (BOOL)removeUserDefinePropertyWithKey:(NSString *)key cacheState:(HMTCacheState)state;
来进行移除属性的操作
参数：key:要删除的属性对应的 key,state:为属性为临时性或持久性枚举
[HMTAgentSDK removeUserDefinePropertyWithKey:@"member_level" cacheState: HMT_CacheTemporary];
¶ 移除所有属性
当 +(BOOL)removeUserDefinePropertyWithKey:(NSString *)key cacheState:(HMTCacheState)state; 接口中传入 key 值为 DELETE-ALL 时(注意大小写)，会移除所有属性
示例:
NSString *key = @"DELETE-ALL";
[HMTAgentSDK removeUserDefinePropertyWithKey: key cacheState: HMT_CacheTemporary];
¶ 一个 Controller 中多个子页面
在应用开发中经常会出现一个 controller 中有多个子页面的情况，如下图，实际页面访问路径为：activity.a -> activity.b.x -> activity.b.y -> activity.c，但在某些页面结构下（比如 x，y 是一个 controller 中两个子页面），此时自动抓取的访问路径可能会变为：activity.a -> activity.b -> activity.c
此时，需要使用定义页面的方法手动的发送 activity.b.x 和 activity.b.y ，如：
//在activity.b.x进入时调用
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
//页面开始(也可以参考2.2.1.3.1使用带回调的方法）
[HMTAgentSDK startTracPage:@"#activity.b.x"];
}
//在activity.b.x离开时调用
- (void)viewWillDisappear:(BOOL)animated {
[super viewWillDisappear:animated];
//页面结束
[HMTAgentSDK endTracPage];
}
//在activity.b.y进入时调用
- (void)viewDidAppear:(BOOL)animated {
[super viewDidAppear:animated];
//页面开始(也可以参考2.2.1.3.1使用带回调的方法）
[HMTAgentSDK startTracPage:@"#activity.b.y"];
}
//在activity.b.y离开时调用
- (void)viewWillDisappear:(BOOL)animated {
[super viewWillDisappear:animated];
//页面结束
[HMTAgentSDK endTracPage];
}
¶ 手动发送缓存
启动时发送的机制下，上报都会存在一定延迟，开发者若觉得有必要增加上报频次可以采用手动发送缓存的方法，如下：
//方法1.处理缓存数据
[HMTAgentSDK pushAllData];
//方法2.处理缓存数据,带回调处理
[HMTAgentSDK pushAllData:^{
NSLog(@"处理完成");
}];
使用上述方法后，会触发手动清除缓存并上报，开发者可根据实际场景触发，如无网切换到有网或用户触发了关键操作等。
¶ 发送自定义的错误
SDK 可以开启对错误的自动捕获，但如果有特殊需求，开发者可以调用本接口，发送自定义的错误信息：
//方法1.发送自定义错误信息
[HMTAgentSDK postErrorData:@"错误内容"];
//方法2.发送自定义错误信息,带回调处理
[HMTAgentSDK postErrorData:@"错误内容" callback:^{
NSLog(@"处理完成");
}];
//方法3.发送自定义错误信息,带自定义属性
NSDictionary *dict = @{
@"错误名称" : @"未知错误",
@"错误地址" : @"0x00001",
@"错误次数" : @"1000000",
};
[HMTAgentSDK postErrorData:@"错误内容" property:dict];
//方法4.发送自定义错误信息,带自定义属性,带回调处理
[HMTAgentSDK postErrorData:@"错误内容" property:dict callback:^{
NSLog(@"处理完成");
}];
¶ 设置账号 ID
系统中默认使用设备 ID 对用户进行标识，若需要统计登录用户或会员这类的指标，需要使用 SDK 的账号 ID 设置方法。
+ (BOOL)bindAccountId:(NSString *)accountid;
使用该方法生成的账号 ID 仅在当次 APP 生命周期内有效，若要注销账号 ID，传空即可；若用户切换账号则传入新值即可。
¶ 设置/采集推送 SDK 的 ID
¶ 1.极光推送
在 iOS App 中，获得 APNs 的 Device Token 后，需要向极光推送注册，注册成功后极光推送会推送 kJPFNetworkDidLoginNotification 登录成功通知，开发者需要监听该通知，之后从极光推送中获取 Registration Id：
[
JPUSHService registrationIDCompletionHandler:^(int resCode, NSString *registrationID) {
if (resCode == 0) {
[HMTAgentSDK bindPushKey:@"jgId" pushId: registrationID];
}
}];
¶ 2.小米推送
在 App 启动时注册小米推送服务，注册成功后获取 APNs 的 Device Token ,注册时需要添加 MiPushSDKDelegate 协议，之后从代理方法中获取 regId
- (void)miPushRequestSuccWithSelector:(NSString *)selector data:(NSDictionary *)data
{
// 请求成功
// 可在此获取regId
if ([selector isEqualToString:@"bindDeviceToken:"]) {
NSLog(@"regid = %@", data[@"regid"]);
[HMTAgentSDK bindPushKey:@"xmId" pushId: data[@"regid"]];
}
}
¶ 3.个推
开发者在集成好个推后需要在 GeTuiSdkDelegate 的代理方法中调用- GeTuiSdkDidRegisterClient:代理方法来获取 clientID 来进行绑定
-(void)GeTuiSdkDidRegisterClient:(NSString *)clientId {
//个推SDK已注册，返回clientId
NSLog(@"\n>>>[GeTuiSdk RegisterClient]:%@\n\n", clientId);
[HMTAgentSDK bindPushKey:@"gtId" pushId: clientId];
}
¶ 自动抓取部分事件
设置部分事件自动埋点采集,默认关闭，开启后可以自动抓取部分按钮事件。（可用于减少手动补码的代码量以及对接阶段的数据测试）
- 自动埋点会获取按钮事件名称，文本内容，控件tag信息等内容
+ (void)enableActionHook:(BOOL)hook;
¶ 可视化布码以及热力图采集功能的开启
¶ 1. 开启可视化布码
开发者在初始化SDK之前调用以下代码接口即可开启可视化布码
+ (void)setAutoTrackEnable:(BOOL)value;
¶ 2.热力图采集
开发者在初始化SDK之前调用以下代码接口即可开启热力图采集功能
+ (void)setThermodynamicEnable:(BOOL)value;