- 平台介绍
- 接入指引
- 版本信息
- 使用流程
- 功能手册
- 操作视频
- 技术文档
- 基础知识
- 客户端SDK
- 服务端SDK
- 数据导入
- API功能
- SQL手册
- DML
- SQL函数
- 日期函数
- convert_tz
- curdate,current_date
- current_timestamp
- curtime,current_time
- date_add
- date_format
- date_sub
- datediff
- day
- dayname
- dayofmonth
- dayofweek
- dayofyear
- from_days
- from_unixtime
- hour
- makedate
- minute
- month
- monthname
- now
- second
- str_to_date
- time_round
- timediff
- timestampadd
- timestampdiff
- to_date
- to_days
- unix_timestamp
- utc_timestamp
- week
- weekday
- weekofyear
- year
- yearweek
- localtime,localtimestamp
- quarter
- last_day
- extract
- date_trunc
- minutes_add
- minutes_diff
- minutes_sub
- seconds_add
- seconds_diff
- seconds_sub
- hours_add
- hours_diff
- hours_sub
- days_add
- days_diff
- days_sub
- weeks_add
- weeks_diff
- weeks_sub
- months_add
- months_diff
- months_sub
- years_add
- years_diff
- years_sub
- 字符串函数
- append_trailing_char_if_absent
- to_base64
- from_base64
- ascii
- length
- bit_length
- char_length
- lpad
- rpad
- lower
- lcase
- upper
- ucase
- initcap
- repeat
- reverse
- char
- concat
- concat_ws
- substr
- substring
- sub_replace
- ends_with
- starts_with
- trim
- ltrim
- rtrim
- null_or_empty
- not_null_or_empty
- hex
- unhex
- elt
- instr
- locate
- find_in_set
- replace
- left
- right
- strleft
- strright
- split_part
- split_by_string
- substring_index
- money_format
- parse_url
- convert_to
- extract_url_parameter
- uuid
- space
- sleep
- 日期函数
- 数据类型
- 数据管理
- 常见问题
- 合规说明
- 资源下载
- AB测试
SDK接入
帮助中心 > 技术文档 > 客户端SDK > iOS SDK > SDK接入
- 1. 开启全埋点
- 2. 用户关联
- 2.1 关联用户ID
- 2.2 获取设备唯一ID
- 2.3 自定义设备唯一ID
- 3. 用户属性
- 3.1 设置用户属性
- 3.2 固定初始值的属性
- 3.3 数值类型的属性
- 3.4 属性取消
- 3.5 清空用户属性
- 4. 自定义埋点
- 4.1 自定义埋点
- 4.2 统计埋点事件时长
- 5. 事件属性
- 5.1 设置事件公共属性
- 5.2 获取预置属性
- 6. 数据存储与发送
- 6.1 上报条件
- 6.2 立即上报(强制上报)
- 6.3 本地数据缓存上限值
- 6.4 清空本地缓存事件
- 7. 全埋点高级控制
- 7.1 开启子页面浏览事件自动采集
- 7.2 自动采集事件的忽略补充
- 7.2.1 忽略某个控件的点击事件
- 7.2.2 忽略某类控件的点击事件
- 7.2.3 忽略页面的浏览事件
- 7.2.4 手动触发页面的点击事件
- 8. 其他功能
- 8.1 开启屏幕方向的自动采集
- 8.2 开启采集页面浏览时长
- 8.3 开启位置信息的自动采集
- 8.4 开启Crash信息的自动采集
- 8.5 开启推送点击事件的自动采集
- 8.6 开启 App 与 H5打通功能
- 8.7 日志开关
- 8.8 禁用SDK
- 8.9 设置属性值长度
iOS SDK 接入流程主要分为两个步骤(两个文档):
1、SDK配置:将对应的SDK集成到您的产品项目中,然后进行初始化代码处理;
2、SDK接入:将需要埋点的数据,按照SDK包装不同的方法进行数据上送,其中功能主要包含两大类:全埋点(自动采集数据上送)、自定义埋点(手动设置业务数据上送)。
1. 开启全埋点
全埋点,也叫无埋点、无码埋点、无痕埋点、自动埋点等。 全埋点,是指无需应用程序开发工程师写代码或者只写少量的代码,即可预先自动收集用户的所有或者绝大部分的行为数据,然后再根据实际的业务分析需求从中筛选出所 需行为数据并进行分析。
全埋点目前可以采集的事件有: AppStart(App 启动)、AppEnd(App 退出)、AppViewScreen(浏览页面) 和 AppClick(控件点击) 四种事件。
SDK初始化前,可通过配置HNBuildOptions实例的autoTrackEventType属性按需开启全埋点类型:
/**
* 可选项: 开启全埋点, 选择开启的全埋点类型,可根据需求进行组合
* 支持四种全埋点类型: App启动、退出、元素点击、页面浏览
*/
// 可依据需求组合开启
options.autoTrackEventType = HNAutoTrackAppStart |
HNAutoTrackAppEnd |
HNAutoTrackAppClick |
HNAutoTrackAppScreen;
2. 用户关联
用户关联是为了对用户进行唯一标识,提高用户行为分析的准确性。
2.1 关联用户ID
当用户注册成功或者进行登录时,需要调用SDK 的用户登录接口:
// 比如:登录手机号、登录邮箱 、用户唯一主键值
[[HinaCloudSDK sharedInstance] setUserUId:@"<您平台用户唯一标识>"];
// 为了准确记录登录用户的行为信息,建议在以下时机各调用一次用户登录接口:
// · 用户在注册成功时
// · 用户登录成功时
// · 已登录用户每次启动 App 时
2.2 获取设备唯一ID
// 如需获取设备唯一id,请在初始化SDK后调用
[[HinaCloudSDK sharedInstance] deviceUId];
注意:
如果 App 引入了 AdSupport 库,SDK 默认使用 IDFA 作为设备唯一 ID,使用 IDFA 能避免用户在重装 App 后设备 ID 发生变化的情况。若没有IDFA,SDK 会使用 IDFV,如果 IDFV 获取失败,则使用随机的 UUID,一般情况下都能够获取到 IDFV。如果使用 IDFV 或 UUID ,当用户卸载重装 App 时设备 ID 会变。
2.3 自定义设备唯一ID
/**
@abstract
在初始化 SDK 之后立即调用,替换sdk分析默认分配的 *匿名 ID*
@discussion
一般情况下,如果是一个注册用户,则应该使用注册系统内的 user_id,调用 SDK 的 setUserUId: 接口。
对于未注册用户,则可以选择一个不会重复的匿名 ID,如设备 ID 等
如果没有调用此方法,则使用 SDK 自动生成的匿名 ID : deviceUId
SDK 会自动将设置的 deviceUId 保存到文件中,下次启动时会从中读取
重要:该方法在 SDK 初始化之后立即调用,可以自定义匿名 ID,不要重复调用。
@param 当前用户的 deviceUId
*/
[[HinaCloudSDK sharedInstance] deviceUId:@"123456"];
3. 用户属性
3.1 设置用户属性
用于直接设置用户的一个或者几个 userDict,建立用户模型。同一个 key 多次设置时,value 值会进行覆盖替换。
[[HinaCloudSDK sharedInstance] set:@{
}];
3.2 固定初始值的属性
对于需要保证只有首次设置时有效的属性,如用户首次注册地点、首次设置的用户昵称等,可以使用setOnce接口进行记录。后续设置已经存在的属性不会覆盖已有数据,如果设置不存在的属性则会自动创建:
// 设定用户 AdSource 渠道为为 "App Store"
[[HinaCloudSDK sharedInstance] setOnce:@"AdSource" to:@"App Store"];
3.3 数值类型的属性
同一个 key 多次设置时,value 值(数值类型)进行累加;常用于记录用户付费次数、付费额度、积分等属性。
// 对单条属性累加
[[HinaCloudSDK sharedInstance] add:@"my_level" by:[NSNumber numberWithInt:1]];
// 对多条属性累加
[[HinaCloudSDK sharedInstance] add:@{
@"my_level":[NSNumber numberWithInt:1],
@"my_golds":[NSNumber numberWithInt:23]
}];
3.4 属性取消
如果需要取消已设置的某个用户属性,可以调用 - unset: 进行取消:
// 取消用户的Level属性
[[HinaCloudSDK sharedInstance] unset:@"Level"];
3.5 清空用户属性
如果想要删除当前这个用户的所有记录,可以调用-deleteUser:
[[HinaCloudSDK sharedInstance] deleteUser];
4. 自定义埋点
4.1 自定义埋点
[[HinaCloudSDK sharedInstance] track:@"WatchVideo"
withProperties:@{@"VideoID":[NSNumber numberWithInt:756487],
@"VideoName":@"Lord of the Rings",
@"IsFree":@(YES)}];
4.2 统计埋点事件时长
需要成对调用计时器的开始、结束等方法,以此来实现对统计时长的事件采集:
// 开始播放电影
[[HinaCloudSDK sharedInstance] trackTimerStart:@"WatchMovie"];
// 暂停播放
[[HinaCloudSDK sharedInstance] trackTimerPause:@"WatchMovie"];
// 恢复播放
[[HinaCloudSDK sharedInstance] trackTimerResume:@"WatchMovie"];
// 结束播放
[[HinaCloudSDK sharedInstance] trackTimerEnd:@"WatchMovie" withProperties:@{@"MovieType":@"classical"}];
注意:
- 只有调用 - trackTimerEnd: 时,SDK 才会真正记录事件
- 多次调用 - trackTimerStart:,以最后一次调用作为计时起点
- 默认情况下,统计的时长不包括用户 App 在后台的时长
5. 事件属性
在进行埋点事件追踪时,您可以根据需求对埋点事件进行属性的定义。目前 SDK 中提供了公共属性用于给每个埋点事件添加属性。
5.1 设置事件公共属性
公共属性是指对于所有事件都需要添加的属性,设置之后 SDK 会在每次触发埋点时,自动获取并添加到触发的事件中。
// 设置事件公共属性
[[HinaCloudSDK sharedInstance] registerCommonProperties:^NSDictionary<NSString *,id> * _Nonnull{
return @{@"level": @"3",
@"balance": @"5642"};
}];
5.2 获取预置属性
如需了解和使用预置属性,可以通过此方法获取预置属性。
// 获取sdk预置的属性
[[HinaCloudSDK sharedInstance] getPresetProperties];
6. 数据存储与发送
6.1 上报条件
iOS SDK 每次触发事件时会检查如下条件,以判断是否向服务器上传数据:
- 当前网络是否符合 flushNetworkPolicy (默认 3G、4G、5G、WiFi)
- 与上次发送的时间间隔是否大于 flushInterval (默认 15 秒)
- 本地缓存的事件条目数是否大于 flushPendSize (默认 100 条)
只有1、2 或1、3 满足时,SDK 才会进行发送数据。以上参数支持自定义,可以通过修改相应参数值来达到控制事件上报的频率:
HNBuildOptions *ops = [[HNBuildOptions alloc] initWithServerURL:@"<数据接收地址>" launchOptions:launchOptions];
// 设置触发间隔,默认 15 * 1000 毫秒
ops.flushInterval = 10 * 1000;
// 设置触发条数,默认 100 条
ops.flushPendSize = 50;
// 设置上报网络策略,默认 3G、4G、5G、WiFi
ops.flushNetworkPolicy = HNNetworkTypeALL;
[HinaCloudSDK startWithConfigOptions:ops];
6.2 立即上报(强制上报)
特殊场景需要立即上报的,可以在事件触发后调用 - flush:
[[HinaCloudSDK sharedInstance] flush];
6.3 本地数据缓存上限值
如果一直不满足上报条件,本地缓存的事件量达到 maxCacheSize 时,每次再触发新的事件,SDK 会依次丢弃老数据,保留最新的数据。maxCacheSize支持自定义,默认10000条:
ops.maxCacheSize = 15000;
6.4 清空本地缓存事件
为适应 GDPR 要求,SDK 可调用 - clear 方法用于清空本地缓存的全部事件:
// 删除本地缓存的全部事件,请慎用!
[[HinaCloudSDK sharedInstance] clear];
7. 全埋点高级控制
全埋点也称自动埋点、无痕埋点,目前SDK支持的全埋点有 App 启动、App 退出、浏览页面和控件点击 四种事件。
7.1 开启子页面浏览事件自动采集
在 SDK初始化 前,通过 HNBuildOptions 实例的 enableAutoTrackChildViewScreen 属性开启自动采集子页面的浏览事件:
options.enableAutoTrackChildViewScreen = YES;
7.2 自动采集事件的忽略补充
SDK开启全埋点后,SDK 支持通过配置忽略部分页面或控件的采集。
7.2.1 忽略某个控件的点击事件
button.hinaDataIgnoreView = YES;
7.2.2 忽略某类控件的点击事件
// 支持多次调用, 对合集进行忽略
[[HinaCloudSDK sharedInstance] disableViewType:[HNButton class]];
[[HinaCloudSDK sharedInstance] disableViewType:[HNView class]];
7.2.3 忽略页面的浏览事件
// 可多次调用,对合集进行忽略
[[HinaCloudSDK sharedInstance] disableAutoTrackViewControllers:@[@"DemoViewController",@"HNBaseViewController"]];
7.2.4 手动触发页面的点击事件
// 可在 viewDidAppear 中触发此操作
[[HinaCloudSDK sharedInstance] trackViewScreen:[UIViewController new]];
8. 其他功能
8.1 开启屏幕方向的自动采集
可以在初始化 SDK 后调用 - enableTrackScreenOrientation: 进行开启,开启后的屏幕方向信息记录在事件的 H_screen_orientation 属性中:
[[HinaCloudSDK sharedInstance] enableTrackScreenOrientation:YES];
8.2 开启采集页面浏览时长
SDK 支持自动采集在离开页面时发送页面离开事件(H_AppPageLeave)来采集页面浏览时长,在初始化 SDK 前,通过 HNBuildOptions 实例的 enableTrackPageLeave 属性开启页面浏览时长事件采集:
// 开启页面离开事件采集
options.enableTrackPageLeave = YES;
8.3 开启位置信息的自动采集
SDK支持自动采集GPS信息,可以在SDK初始化后调用 enableTrackGPSLocation 方法进行开启,采集后的经纬度信息会乘以10⁶后记录在 H_longitude、H_latitude 属性中:
[[HinaCloudSDK sharedInstance] enableTrackGPSLocation:YES];
注意:如果app业务中未开启定位权限,针对审核问题,开启此项功能后需在plist文件中添加相关用途说明。
8.4 开启Crash信息的自动采集
说明:初始化 SDK 时,通过如下配置,即可开启App Crash信息的采集。
SDK 默认关闭 Crash 信息采集,开启采集后,App Crash 时,会触发 AppCrashed 事件,堆栈信息记录在 app_crashed_reason 属性中。
HNBuildOptions *options = [[HNBuildOptions alloc] initWithServerURL:kAppServerURL launchOptions:launchOptions];
options.enableTrackAppCrash = YES;
[HinaCloudSDK startWithConfigOptions:options];
8.5 开启推送点击事件的自动采集
在SDK初始化 前,通过 HNBuildOptions 实例的 enablePushAutoTrack 属性开启推送点击事件的自动采集:
options.enablePushAutoTrack = YES;
// 如需设置推送唯一id,请在初始化SDK后调用
[[HinaCloudSDK sharedInstance] userPushKey:@"###" pushId:@"###"];
8.6 开启 App 与 H5打通功能
所谓打通,是指 H5 集成 JavaScript 数据采集 SDK 后,H5 触发的事件不是直接同步给服务端,而是先发给 App 端的数据。
采集 SDK,经 App 端数据采集 SDK 二次加工处理后入本地缓存再进行同步。
这样设计的目的主要是从以下几个角度考虑:
1、数据丢失率;
2、数据准确性;
3、用户标识。
初始化 SDK 时,进行如下配置,即可开启 App 打通 H5 功能:
options.enableJSBridge = YES;
8.7 日志开关
#ifdef DEBUG
// 开启 Log,可方便开发时进行调试
options.enableLog = YES;
#endif
然后在 IDE (如 Xcode )日志控制台中筛选 SALog 关键词:
埋点事件触发成功时,SDK 会输出 【track event】 开头的事件数据;
埋点事件触发失败时,SDK 会输出相应的错误原因;
事件数据上报成功时,SDK 会输出 【valid message】字段开头的事件数据;
事件数据上报失败时,SDK 会输出 【invalid message】 字段开头的事件数据并输出错误原因。
8.8 禁用SDK
// 禁用 SDK,默认为 NO
// 禁用后,SDK 将不会触发事件,也不会发送网络请求
// 在某些情形如应用审核期间,可以结合服务器开关配合使用此功能,提高审核通过率
options.disableSDK = NO;
8.9 设置属性值长度
说明:属性值value的长度支持自定义,SDK默认限制属性value长度为1024,支持设置的有效长度为1024~5120,超出设置的阈值,SDK会做截断处理。
options.maxPropertyValueLength = 3000;
最后编辑:邓昊 更新时间:2024-09-05 21:06