最近更新时间：2023.06.08 11:39:40
首次发布时间：2022.03.30 22:51:18
上报事件和属性前，请先阅读数据格式介绍。
6.13.0 之后的版本允许在 startTrack 之前调用，用于设置初始化的登录态。
6.13.0 之前的版本只有在 SDK 启动完成之后调用生效。
如您的产品中有账户体系，请在用户登录后立即设置uuid，以保证用户登录前后口径一致性。
Objective-C请参考：
#import <RangersAppLog/RangersAppLog.h> // 设置您账号体系的ID, 并保证其唯一性 [BDAutoTrack setCurrentUserUniqueID:@"{{USER_UNIQUE_ID}}"];
Swift请参考：
BDAutoTrack.setCurrentUserUniqueID("{{USER_UNIQUE_ID}}")
在账户登出时调用。
Objective-C请参考：
[BDAutoTrack clearUserUniqueID];
Swift请参考：
BDAutoTrack.clearUserUniqueID()
设置用户属性，存在则覆盖，不存在则创建。
Objective-C请参考：
// 示例：设置用户属性，属性名为key，属性值为value NSDictionary *profileDict = @{@"key": @("value")}; [BDAutoTrack profileSet:profileDict];
Swift请参考：
// 示例：设置用户属性，属性名为key，属性值为value let profileDict: [AnyHashable: Any] = [ "key": "value" ] BDAutoTrack.profileSet(profileDict)
设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。
Objective-C请参考：
// 示例：设置用户属性，属性名为key_once，属性值为value_once NSDictionary *profileDict = @{@"key_once": @("value_once")}; [BDAutoTrack profileSetOnce:profileDict];
Swift请参考：
// 示例：设置用户属性，属性名为key_once，属性值为value_once let profileDict: [AnyHashable: Any] = [ "key_once": "value_once" ] BDAutoTrack.profileSetOnce(profileDict)
设置数值类型的属性，可进行累加。
Objective-C请参考：
// 示例：设置用户属性，属性名为key，属性值为1 [BDAutoTrack profileIncrement:@{@"key": @(1)}];
Swift请参考：
// 示例：设置用户属性，属性名为key，属性值为1 let profileDict: [AnyHashable: Number] = [ "key": 1 ] BDAutoTrack.profileIncrement(profileDict)
设置List类型的用户属性，可持续向List内添加。
Objective-C请参考：
// 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append [BDAutoTrack profileAppend:@{ @"key": @[@"value_append"] }];
Swift请参考：
// 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append BDAutoTrack.profileAppend([["key"]:["value_append"]])
删除用户的属性。
Objective-C请参考：
// 示例：删除用户属性，属性名为key [BDAutoTrack profileUnset:@"key"];
Swift请参考：
// 示例：删除用户属性，属性名为key BDAutoTrack.profileUnset("key")
用户行为日志采用事件event+属性params的形式，事件一般对应多个属性，也可以仅有事件没有属性。代码埋点方案一般由数据分析师或产品运营设计。
仅上报事件的代码埋点，示例如下：
Objective-C请参考：
// 示例：上报事件event，该事件不包含属性 // 置于业务逻辑对应位置 [BDAutoTrack eventV3:@"event" params:nil];
Swift请参考：
// 示例：上报事件event，该事件不包含属性 // 置于业务逻辑对应位置 BDAutoTrack.eventV3("event", params: nil)
上报事件和对应属性的代码埋点，示例如下：
Objective-C请参考：
// 示例：上报事件event，该事件包含两个属性 // 一个string类型的属性，属性名为key_string，属性值为value_string //. 一个int类型的属性，属性名为key_int，属性值为10 // 置于业务逻辑对应位置 [BDAutoTrack eventV3:@"event" params:@{@"key_string":@"value_string", @"key_int": @(10)}];
Swift请参考：
// 示例：上报事件event，该事件包含两个属性 // 一个string类型的属性，属性名为key_string，属性值为value_string //. 一个int类型的属性，属性名为key_int，属性值为10 // 置于业务逻辑对应位置 BDAutoTrack.eventV3("event", params: ["key_string": "value_string", "key_int": 10])
如需在每个事件中都包括某属性，可通过公共属性设置，无需在每个事件中重复设置。公共属性只需设置一次，即可包括在所有代码埋点事件、预置事件和全埋点事件中。
Objective-C请参考：
/* * 示例：设置自定义的公共属性，属性名为key_public，属性值为value_public * 关于自定义 “公共属性” 请注意： * 1. 上报机制是随着每一次日志发送进行提交，默认的日志发送频率是1分钟， * 所以如果在一分钟内连续修改自定义公共属性，按照日志发送前的最后一次修改为准； * 2. 不推荐高频次修改，如每秒修改一次。 */ [BDAutoTrack setCustomHeaderValue:@"value_public" forKey:@"key_public"];
Swift请参考：
/* * 示例：设置自定义的公共属性，属性名为key_public，属性值为value_public * 关于自定义 “公共属性” 请注意： * 1. 上报机制是随着每一次日志发送进行提交，默认的日志发送频率是1分钟， * 所以如果在一分钟内连续修改自定义公共属性，按照日志发送前的最后一次修改为准； * 2. 不推荐高频次修改，如每秒修改一次。 */ BDAutoTrack.setCustomHeaderValue { () -> [String : Any] in return ["key_public":"value_public"] }
Objective-C请参考：
// 示例：移除属性名为key_public的公共属性 [BDAutoTrack removeCustomHeaderValueForKey:@"key_public"];
Swift请参考：
// 示例：移除属性名为key_public的公共属性 BDAutoTrack.removeCustomHeaderValueForKey("key_public");
Objective-C请参考：
#import <RangersApplog/BDAutoTrackNotifications.h> // 在初始化 SDK 之前设置监听 [[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(onRegisterSuccess:) name:BDAutoTrackNotificationRegisterSuccess object:nil]; //SDK 初始化代码部分 //然后在 SDK 初始化之后设置回调 - (void)onRegisterSuccess:(NSNotification *)noti { NSString *dids = [noti.userInfo objectForKey:kBDAutoTrackNotificationRangersDeviceID]; NSString *ssids = [noti.userInfo objectForKey:kBDAutoTrackNotificationSSID]; NSLog(@"onRegisterSuccess.dids：%@", dids); // 获取设备bddid NSLog(@"onRegisterSuccess.ssids：%@", ssids); // 获取SSID }
Swift请参考：
NotificationCenter.default.addObserver(self, selector: #selector(onRegisterSuccess), name: NSNotification.Name(rawValue: BDAutoTrackNotificationRegisterSuccess), object: nil) func onRegisterSuccess(noti: Notification) { let did = noti.userInfo[kBDAutoTrackNotificationRangersDeviceID] let ssid = noti.userInfo[kBDAutoTrackNotificationSSID] print("onRegisterSuccess.dids：\(did)") print("onRegisterSuccess.ssids：\(ssid)") }
Objective-C请参考：
// SDK版本号格式为X.X.X [BDAutoTrack SDKVersion];
Swift请参考：
BDAutoTrack.sdkVersion()
SDK提供方法用以获取各类通知。各通知在BDAutoTrackNotifications.h头文件中均有描述。
// SDK 注册成功通知 BDAutoTrackNotificationRegisterSuccess // SDK 注册请求失败通知 BDAutoTrackNotificationRegisterFailure // 激活成功通知 BDAutoTrackNotificationActiveSuccess // SDK ABTest配置拉取成功通知 BDAutoTrackNotificationABTestSuccess // SDK ABTestVid发生变化时候的通知 BDAutoTrackNotificationABTestVidsChanged
SDK 默认采集以下信息，并作为用户公共属性，可在增长分析(DataFinder)中分组和筛选。
| 字段名称 | 字段类型 | 参数名称 |
|---|---|---|
| os | string | 设备系统，对应产品内属性为 os_name。 |
| os_version | string | 操作系统版本 |
| app_version | string | App 版本 |
| app_version_minor | string | 次版本号，App四位版本号，设置[OKApplicationInfo sharedInstance].buildVersion = @"1.2.3.4"; |
| channel | string | 下载渠道（设置后可覆盖），对应产品内属性为 app_channel。 |
| device_model | string | 设备型号 |
| region | string | 操作系统国家 |
| language | string | 系统语言 |
| sdk_version | string | SDK版本 |
| timezone | int | 时区 例如 8 |
| tz_offset | int | 时区偏移量，对应产品内属性为 tz_offset，例如 28800。 |
| tz_name | string | 时区名称，例如 Asia/Shanghai。 |
| carrier | string | 运营商 |
| resolution | string | 分辨率 |
| device_brand | string | 设备品牌 |
| access | string | 网络类型 |
如果您曾经使用火山引擎的游戏增长分析产品（该产品已经下架），目前在使用增长分析（DataFinder）产品，为了提升您的埋点效率，SDK 提供了内置接口，您只需要根据提示传入指定的参数即可。
#import "BDAutoTrack+GameTrack.h" //请先引入正确的头文件 /** 广告按钮点击：gt_ad_button_click ad_type string 广告类型：激励视频、插屏、banner等，直接使用汉字或者英文进行标识 ad_position_type string 广告点位类型：按照提供分类接入 ad_position string 广告点位：复活、翻倍、试用、buff、奖励道具、新道具、减CD等，直接使用文字或者英文进行标识 触发条件：用户点击app内各广告位button时。 */ - (void)adButtonClickEventWithADType:(NSString *)adType positionType:(NSString *)positionType position:(NSString *)position otherParams:(nullable NSDictionary *)otherParams; /** 广告开始展示：gt_ad_show ad_type string 广告类型：激励视频、插屏、banner等，直接使用汉字或者英文进行标识 ad_position_type string 广告点位类型：按照提供分类接入 ad_position string 广告点位：复活、翻倍、试用、buff、奖励道具、新道具、减CD等，直接使用文字或者英文进行标识 触发条件：用户点击并观看广告时。穿山甲广告有回调，可以直接获取。 */ - (void)adShowEventWithADType:(NSString *)adType positionType:(NSString *)positionType position:(NSString *)position otherParams:(nullable NSDictionary *)otherParams; /** 广告结束展示：gt_ad_show_end ad_type string 广告类型：激励视频、插屏、banner等，直接使用汉字或者英文进行标识 ad_position_type string 广告点位类型：按照提供分类接入 ad_position string 广告点位：复活、翻倍、试用、buff、奖励道具、新道具、减CD等，直接使用文字或者英文进行标识 result string 广告观看结果：跳过、成功、失败等，使用英文进行标识. 跳过标记为skip, 成功标记为success，失败为fail 触发条件：用户观看广告结束时。 */ - (void)adShowEndEventWithADType:(NSString *)adType positionType:(NSString *)positionType position:(NSString *)position result:(NSString *)result otherParams:(nullable NSDictionary *)otherParams; /** （总等级）升级和经验：gt_levelup lev int 当前玩家等级 get_exp int 获得经验 method string 获得经验途径：闯关成功、引导完成、领取奖励等，使用汉字或者英文进行标识 aflev int 用户获得经验后等级，如获得经验未导致升级，则lev=aflev，如导致升级，则lev<aflev 触发条件：用户获得经验或者等级发生变化时。 */ - (void)levelUpEventWithLevel:(NSInteger)level exp:(NSInteger)exp method:(NSString *)method afterLevel:(NSInteger)afterLevel otherParams:(nullable NSDictionary *)otherParams; /** 开始玩法：gt_start_play ectype_name string 针对闯关性质玩法，标注关卡名称 触发条件：用户开始玩法时。 */ - (void)startPlayEventWithName:(NSString *)ecTypeName otherParams:(nullable NSDictionary *)otherParams; /** 结束玩法：gt_end_play ectype_name string 针对闯关性质玩法，标注关卡名称 result string 玩法的结果：未完成、成功、失败等，使用英文进行标识. 未完成标记为uncompleted, 成功标记为success，失败为fail duration int 消耗时间，单位秒 触发条件：用户结束玩法时，涵盖中途退出、完成但失败和完成且成功。 */ - (void)endPlayEventWithName:(NSString *)ecTypeName result:(NSString *)result duration:(NSInteger)duration otherParams:(nullable NSDictionary *)otherParams; /** 获得游戏币：gt_get_coins coin_type string 货币类型：元宝、绑元、金币、银币等，使用文字或者英文进行标识 method string 获得途径：观看激励视频、闯关成功、活动奖励等，使用文字或者英文进行标识 coin_num int 获得数量 触发条件：用户获得游戏币，导致游戏币增加时 */ - (void)getCoinsEventWitType:(NSString *)coinType method:(NSString *)method coinNumber:(NSInteger)number otherParams:(nullable NSDictionary *)otherParams; /** 消耗游戏币：gt_cost_coins coin_type string 货币类型：元宝、绑元、金币、银币等，使用文字或者英文进行标识 method string 消耗途径：复活、购买道具、解锁关卡等，使用文字或者英文进行标识 coin_num int 消耗数量 触发条件：用户消耗游戏币，导致游戏币减少时。 */ - (void)costCoinsEventWitType:(NSString *)coinType method:(NSString *)method coinNumber:(NSInteger)number otherParams:(nullable NSDictionary *)otherParams; /** 内购充值相关：purchase content_type string 内购充值内容类型 content_name string 内购充值内容名称 content_id string 内购充值内容id content_num int 内购充值内容的数量 payment_channel string 支付渠道：例如 支付宝，微信等 currency string 支付货币类型 is_success string 支付是否成功 currency_amount int 支付的金额，单位元 触发条件：用户完成内购充值并获得对应的游戏内货币和道具时 */ - (void)purchaseEventWithContentType:(NSString *)contentType contentName:(NSString *)contentName contentID:(NSString *)contentID contentNum:(NSInteger)contentNum channel:(NSString *)channel currency:(NSString *)currency isSuccess:(NSString *)isSuccess currencyAmount:(NSInteger)currencyAmount otherParams:(nullable NSDictionary *)otherParams; /** 初始化信息：gt_init_info lev int 玩家等级 coin_type string 获得货币的类型 coin_left int 用户身上剩余的货币数量 role_id string 玩家角色id-cp侧 触发条件：用户启动游戏，初始化完成时上报 */ - (void)gameInitInfoEventWithLevel:(NSInteger)level coinType:(NSString *)coinType coinLeft:(NSInteger)coinLeft otherParams:(nullable NSDictionary *)otherParams;
本功能在6.10.0+后开始支持。
当组件出现在屏幕可视范围内会自动触发一个曝光事件。
Exposure文件方式集成需要引入对应的库文件。
pod 'RangersAppLog', 'SDK_VERSION', :subspecs => [ ... 'Exposure', ... ]
//相关的功能设置引入头文件 //modular方式集成 @import RangersAppLog; #import <RangersAppLog/BDAutoTrackExposure.h>
Objective-C 请参考：
config.exposureEnabled = YES; // 全局功能控制开关 YES|NO. 默认为开启
Swift 请参考：
config.exposureEnabled = true
设置组件触发曝光的最小进入主屏幕视图面积占比。
默认为：
0：表示采用 1 pixel 进入屏幕触发曝光。
(0~1]：浮点数表示占比 0～100% 会触发曝光。
Objective-C 请参考：
// BDAutoTrackConfig 全局设置，组件独立的配置可以在 BDViewExposureData 设置 [config.exposureConfig areaRatio:0.5];
Swift 请参考：
config.exposureConfig.areaRatio(0.5)
说明
此功能仅基于主窗口判断曝光，暂未支持子视图遮挡的计算。
对组件实例进行曝光监控。
Objective-C 请参考：
BDViewExposureData *opt = [BDViewExposureData new]; opt.eventName = @"view_did_exposure"; // 如果不设置，埋点采用bav2b_exposure opt.properties = @{}; // 用户自定参数 opt.config = [[BDViewExposureConfig defaultConfig] areaRatio:0.5]; // 开启针对于视图的检测 // view 用户的视图对象实例 // opt 埋点数据以及配置 [[BDAutoTrack sharedTrack] observeViewExposure:YOUR_VIEW withData:opt]; // 停止针对于视图的检测 [[BDAutoTrack sharedTrack] disposeViewExposure:YOUR_VIEW];
Swift 请参考：
let opt = BDViewExposureData() opt.eventName = "view_did_exposure" opt.properties = [:] opt.config = BDViewExposureConfig.default().areaRatio(0.5) BDAutoTrack.shared().observeViewExposure(YOUR_VIEW, with: opt) BDAutoTrack.shared().disposeViewExposure(YOUR_VIEW)
注意
本开关仅限调试debug阶段使用，请勿在线上包开启。
开启可视化调试功能后，对组件曝光功能进行调试。
开启监控曝光的组件，生成红色的边框。
组件触发曝光，生成半透明的浮层。
Objective-C 请参考：
[config.exposureConfig enableVisualDiagnosis:YES];
Swift 请参考：
config.exposureConfig.enableVisualDiagnosis(true)
开启全埋点事件采集开关后，会默认采集页面事件和 View 点击事件等。
根据集成方式的差异，在项目中引入对应的 subspec 模块或者静态库文件。
Objective-C 请参考：
// 开启全埋点采集，默认为YES config.autoTrackEnabled = YES; // 开启WebView全埋点采集，默认为YES config.H5AutoTrackEnabled = YES;
Swift 请参考：
config.autoTrackEnabled = true config.H5AutoTrackEnabled = true
本小节功能于 6.11.0+ 版本起支持。
允许全埋点事件类型的配置，具体定义见 <BDCommonEnumDefine.h>。
BDAutoTrackDataTypePage - 页面浏览事件
BDAutoTrackDataTypeClick - 用户点击事件
BDAutoTrackDataTypePageLeave - 页面浏览结束事件
Objective-C 请参考：
config.autoTrackEventType = BDAutoTrackDataTypeAll;
Swift 请参考：
config.autoTrackEventType = BDAutoTrackDataType.all
请在 init 方法中设置参数值，否则首次触发页面浏览事件时，参数值可能为空。
通过 UIViewController 扩展 API 自定义页面浏览事件的参数。
/*! @abstract 手动设置的PageTitle @discussion 如果设置，页面切换的时候会采集 @discussion 如果设置，该VC里面的View被点击的时候会采集 */ @property (nonatomic, copy) NSString *bdAutoTrackPageTitle; /*! @abstract 手动设置的PageID @discussion 如果设置，页面切换的时候会采集 @discussion 如果设置，该VC里面的View被点击的时候会采集 */ @property (nonatomic, copy) NSString *bdAutoTrackPageID; /*! @abstract 手动设置的PagePath @discussion 如果设置，页面切换的时候会采集 @discussion 如果设置，该VC里面的View被点击的时候会采集 */ @property (nonatomic, copy) NSString *bdAutoTrackPagePath; /*! @abstract 手动设置的extra信息 @discussion 如果设置，页面切换的时候会采集 @discussion 如果设置，该VC里面的View被点击的时候会采集 */ @property (nonatomic, copy) NSDictionary<NSString*, NSString *> *bdAutoTrackExtraInfos; /*! @abstract 自定义采集属性，相同 key 会覆盖默认采集的 params @discussion 如果设置，页面切换的时候会采集 @discussion 如果设置，该VC里面的View被点击的时候会采集 */ @property (nonatomic, copy) NSDictionary<NSString*, NSObject *> *bdAutoTrackPageProperties;
通过 UIView、UIBarButtonItem 扩展 API 自定义点击事件的参数。
/*! @abstract 这个对应新增的 element_id 字段，bdAutoTrackViewID 对应的是 element_manual_key 字段 @discussion 如果设置，被点击的时候会采集 */ @property (nonatomic, copy) NSString *bdAutoTrackElementID; /*! @abstract 手动设置的ViewID @discussion 如果设置，被点击的时候会采集，可以唯一标志该View */ @property (nonatomic, copy) NSString *bdAutoTrackViewID; /*! @abstract 手动设置的ViewContent @discussion如果设置，被点击的时候会采集 */ @property (nonatomic, copy) NSString *bdAutoTrackViewContent; /*! @abstract 手动设置的extra信息 @discussion 如果设置，被点击的时候会采集 */ @property (nonatomic, copy) NSDictionary<NSString*, NSString *> *bdAutoTrackExtraInfos; /*! @abstract 自定义采集属性，相同 key 会覆盖默认采集的 params @discussion 如果设置，被点击的时候会采集 */ @property (nonatomic, copy) NSDictionary<NSString*, NSObject *> *bdAutoTrackViewProperties; /*! @abstract 自定义采集开发 @discussion 如果设置 YES，被点击的时候埋点会被忽略 */ @property (nonatomic, assign) BOOL bdAutoTrackIgnoreClick;
/*! @abstract 忽略UIViewController中自动采集的浏览埋点 @discussion 忽略范围作用域为自身类，并不影响继承关系，例如 BViewController 继承于 AViewController， 如果都忽略需要传入@[[AViewController class],[BViewController class]] @param controllerClasses 传入需要忽略的类名 @[[TestViewController class], [UserViewController class]] */ - (void)ignoreAutoTrackPage:(NSArray<Class> *)controllerClasses;
Objective-C 请参考：
[[BDAutoTrack sharedTrack] ignoreAutoTrackPage:@[YOUR_ViewController.class]];
Swift 请参考：
BDAutoTrack.shared().ignorePage([YOUR_ViewController.classForCoder()])
/*! @abstract 忽略控件中自动采集的点击埋点 @discussion 忽略范围作用域为自身类 @param viewClasses 传入需要忽略的类名 @[[AButton class], [ALabel class]] */ - (void)ignoreAutoTrackClick:(NSArray<Class> *)viewClasses;
Objective-C 请参考：
[[BDAutoTrack sharedTrack] ignoreAutoTrackClick:@[YOUR_VIEW.class]];
Swift 请参考：
BDAutoTrack.shared().ignoreClick([YOUR_VIEW.classForCoder()])
/*! * @abstract 代码触发页面浏览埋点上报 * @param controller 可以传递 UIViewController 以及实现了 BDAutoTrackable协议的对象 * @result 是否成功 */ - (BOOL)trackPage:(id<BDAutoTrackable>)controller; /*! * @abstract 代码触发页面浏览埋点上报 * @param controller 可以传递 UIViewController * @param params 用户自定义参数，进行 [NSJSONSerialization isValidJSONObject:] 验证 * @result 是否成功 */ - (BOOL)trackPage:(id)controller withParameters:(nullable NSDictionary<NSString *,id> *)params;
Objective-C请参考：
[[BDAutoTrack sharedTrack] trackPage:YOUR_VIEWCONTROLLER_INSTANCE];
Swift请参考：
BDAutoTrack.shared().trackPage(YOUR_VIEWCONTROLLER_INSTANCE)
/*! * @abstract 代码触发点击埋点上报 * @param view 可以传递 UIView 等控件对象 以及实现了 BDAutoTrackable协议的对象 * @result 是否成功 */ - (BOOL)trackClick:(id<BDAutoTrackable>)view; /*! * @abstract 代码触发点击埋点上报 * @param view 可以传递 UIView 等控件对象 以及实现了 BDAutoTrackable协议的对象 * @param params 用户自定义参数，进行 [NSJSONSerialization isValidJSONObject:] 验证 * @result 是否成功 */ - (BOOL)trackClick:(id<BDAutoTrackable>)view withParameters:(nullable NSDictionary<NSString *,id> *)params;
Objective-C请参考：
[[BDAutoTrack sharedTrack] trackClick:YOUR_COMPONENT];
Swift 请参考：
BDAutoTrack.shared().trackClick(YOUR_COMPONENT)
本小节功能在6.10.2+后开始支持。
带有时间属性的事件可以使用时长事件采集接口，例如采集视频播放时长事件等。示例：
// 在视频开始播放时调用 [[BDAutoTrack sharedTrack] startDurationEvent:@"play"]; // 在视频暂停播放时调用 [[BDAutoTrack sharedTrack] pauseDurationEvent:@"play"]; // 在视频继续播放时调用 [[BDAutoTrack sharedTrack] resumeDurationEvent:@"play"]; // 在结束播放时调用，此时会上报一个play事件，且带有$event_duration属性（记录了播放时长，单位毫秒） [[BDAutoTrack sharedTrack] stopDurationEvent:@"play" properties:@{@"moive_name":@"xxx"}];