上报事件和属性前,请先阅读数据格式介绍。
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
设置组件触发曝光的最小进入主屏幕视图面积占比。
默认为:
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 点击事件等。
应用场景
典型场景 | 场景说明 |
---|---|
用户行为分析 | 了解用户在应用中的行为路径,例如:用户点击了哪些按钮,用户浏览了哪些页面,用户在特定页面停留的时间。 |
A/B测试 | 帮助评估不同版本的功能或界面对用户行为的影响。例如:比较两个不同界面布局的点击率,测试不同功能实现方式对用户使用率的影响。 |
问题诊断 | 帮助快速发现和定位应用中的问题。例如:用户在某个页面频繁退出或崩溃,某些功能的使用率突然下降。 |
运营活动效果评估 | 帮助评估各种运营活动的效果,例如促销活动、推送通知等。例如:某次推送通知的点击率和转化率,某个促销活动的参与度和效果。 |
全埋点能力支持
能力支持 | 能力说明 |
---|---|
页面访问 |
|
点击 |
|
曝光 | UIView及子类曝光 |
根据集成方式的差异,在项目中引入对应的 subspec 模块或者静态库文件。
Objective-C
请参考:
// 开启全埋点采集,默认为YES config.autoTrackEnabled = YES; // 开启WebView全埋点采集,默认为YES config.H5AutoTrackEnabled = YES;
Swift
请参考:
config.autoTrackEnabled = true config.H5AutoTrackEnabled = true
本小节功能于 6.11.0+ 版本起支持。
允许全埋点事件类型的配置,具体定义见 <BDCommonEnumDefine.h>
。
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"}];