本文为您介绍iOS端为您提供的一系列API，您可以结合埋点规划调用对应API进行埋点。

sharedTrackWithConfig #

• 作用：初始化单例，调用时机：1、必须在应用启动时调用，即在 application:didFinishLaunchingWithOptions: 中调用；2、必须在主线程中调用；3、必须在 SDK 其他方法调用之前调用。

• 定义：+ (void)sharedTrackWithConfig:(BDAutoTrackConfig *)config

• 参数：

  参数名	类型	必填	说明
  config	BDAutoTrackConfig	是

• 示例：
  Objective-C请参考：

  BDAutoTrackConfig* config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
  [BDAutoTrack sharedTrackWithConfig:config]; 
  

  Swift请参考：

  let config = BDAutoTrackConfig(appID: "{{APPID}}")
  BDAutoTrack.sharedTrack(with: config)
  

sharedTrack #

• 作用：如果已初始化，则返回之前初始化好的单例；否则返回nil。本身不会做初始化。调用这个方法之前，必须先调用 sharedTrackWithConfig。

• 定义：+ (instancetype)sharedTrack

• 示例：
  Objective-C请参考：

  [BDAutoTrack sharedTrack];
  

  Swift请参考：

  BDAutoTrack.shared()
  

startTrack #

• 作用：启动SDK单例，调用时机：1、必须在应用启动时调用，即在 application:didFinishLaunchingWithOptions: 中调用；2、必须在主线程中调用。

• 定义：+ (void)startTrack

• 示例：
  Objective-C请参考：

  [[BDAutoTrack sharedTrack] startTrack];
  

  Swift请参考：

  BDAutoTrack.shared().start()
  

trackWithConfig #

• 作用：初始化方法，初始化一个实例。初始化接口可以重复调用，会返回一个实例，推荐返回之后，引用住这个实例，下次上报方便使用。

• 定义：+ (nullable instancetype)trackWithConfig:(BDAutoTrackConfig *)config

• 参数：

  参数名	类型	必填	说明
  config	BDAutoTrackConfig	是

• 示例：
  Objective-C请参考：

  BDAutoTrackConfig* config1 = [BDAutoTrackConfig configWithAppID:@"{{APPID_1}}" launchOptions:launchOptions];
  BDAutoTrack *track1 = [BDAutoTrack trackWithConfig:config1];
  [track1 startTrack];
  
  BDAutoTrackConfig* config2 = [BDAutoTrackConfig configWithAppID:@"{{APPID_2}}" launchOptions:launchOptions];
  BDAutoTrack *track2 = [BDAutoTrack trackWithConfig:config2];
  [track2 startTrack];
  

  Swift请参考：

  let config1 = BDAutoTrackConfig.init(appID: "{{APPID_1}}", launchOptions: launchOptions)
  let tracker1 = BDAutoTrack.init(config: config1);
  tracker1!.start()
  
  let config2 = BDAutoTrackConfig.init(appID: "{{APPID_2}}", launchOptions: launchOptions)
  let tracker2 = BDAutoTrack.init(config: config2);
  tracker2!.start()
  

setRequestHostBlock #

• 作用：设置自定义的Host回调，设置一次即可，不需要多次设置，如果多次设置，会覆盖之前的初始化或者上一次设置的回调，如果为nil会清空回调。

• 定义：+ (void)setRequestHostBlock:(nullable BDAutoTrackRequestHostBlock)requestHostBlock

• 参数：

  参数名	类型	必填	说明
  requestHostBlock	BDAutoTrackRequestHostBlock	是

• 示例：
  Objective-C请参考：

  BDAutoTrackRequestHostBlock block = ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
      return @"https://gator.volces.com";
  };
  [BDAutoTrack setRequestHostBlock:block];
  

  Swift请参考：

  BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in
      return "https://gator.volces.com"
  }
  

setCurrentUserUniqueID #

• setCurrentUserUniqueID:uniqueID #

• 作用：设置用户登录态。在初始化之后设置user_unique_id值，SDK会保存，因此只需要发生变化的时候设置。

• 定义：+ (BOOL)setCurrentUserUniqueID:(nullable NSString *)uniqueID

• 参数：

  参数名	类型	必填	说明
  uniqueID	NSString	是，可nil

• 示例：
  Objective-C请参考：

  [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"{{USER_UNIQUE_ID}}"]; 
  

  Swift请参考：

  BDAutoTrack.setCurrentUserUniqueID("{{USER_UNIQUE_ID}}")
  

• setCurrentUserUniqueID:uniqueID:type #

• 作用：设置用户登录态及用户类型。在初始化之后设置user_unique_id值以及类型，SDK会保存，因此只需要发生变化的时候设置。

• 定义：+ (BOOL)setCurrentUserUniqueID:(nullable NSString *)uniqueID withType:(nullable NSString *)type;

• 参数：

  参数名	类型	必填	说明
  uniqueID	NSString	是，可nil
  type	NSString	是，可nil

• 示例：
  Objective-C请参考：

  [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"{{USER_UNIQUE_ID}}" withType:@"{{USER_UNIQUE_ID类型}}"]; 
  

  Swift请参考：

  BDAutoTrack.setCurrentUserUniqueID("{{USER_UNIQUE_ID}}", withType:"{{USER_UNIQUE_ID类型}}")
  

clearUserUniqueID #

• 作用：退出用户登录态。

• 定义：+ (void)clearUserUniqueID

• 示例：
  Objective-C请参考：

  [BDAutoTrack clearUserUniqueID];
  

  Swift请参考：

  BDAutoTrack.clearUserUniqueID()
  

eventV3 #

• 作用：上报事件，在初始化之后设置才能调用。

• 定义：+ (BOOL)eventV3:(NSString *)event params:(nullable NSDictionary *)params

• 参数：

  参数名	类型	必填	说明
  event	NSString	是	事件名称，不能为nil或空字符串
  params	NSDictionary	是，可nil	事件参数。可以为空或者nil，如果非空，需要可序列化成json，建议自定义属性不超过 50kb，避免影响整体数据上报，超过 50kb 数据会丢弃所有自定义属性调整为报错信息 调整后报错事件示例： { "params":{ "description":"event param too large" }, "event":原事件事件名, }

• 示例：
  Objective-C请参考：

  BDAutoTrackRequestHostBlock block = ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
      return @"https://gator.volces.com";
  };
  [BDAutoTrack setRequestHostBlock:block];
  

  Swift请参考：

  BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in
      return "https://gator.volces.com"
  }
  

setCustomHeaderValue #

• 作用：设置自定义的公共属性（非持久化）。

• 定义：+ (void)setCustomHeaderValue:(nullable id)value forKey:(NSString *)key

• 参数：

  参数名	类型	必填	说明
  value	id	是，可nil	自定义上报value，一般需要传NSString或者数字，或者nil
  key	NSString	是	自定义上报key

• 示例：
  Objective-C请参考：

  [BDAutoTrack setCustomHeaderValue:@"value_public" forKey:@"key_public"];
  

  Swift请参考：

  BDAutoTrack.setCustomHeaderValue { () -> [String : Any] in
      return ["key_public":"value_public"]
  }
  

removeCustomHeaderValueForKey #

• 作用：移除自定义的公共属性。

• 定义：+ (void)removeCustomHeaderValueForKey:(NSString *)key

• 参数：

  参数名	类型	必填	说明
  key	NSString	是	自定义上报key

• 示例：
  Objective-C请参考：

  [BDAutoTrack setCustomHeaderValue:@"value_public" forKey:@"key_public"];
  

  Swift请参考：

  BDAutoTrack.setCustomHeaderValue { () -> [String : Any] in
      return ["key_public":"value_public"]
  }
  

#

configWithAppID #

• 作用：根据App ID获得一个config对象。

• 定义：+ (instancetype)configWithAppID:(NSString *)appID launchOptions:(nullable NSDictionary<id,id> *)launchOptions

• 参数：

  参数名	类型	必填	说明
  appID	NSString	是	注册应用时获取的AppID
  launchOptions	NSDictionary<id,id>	是，可nil	应用启动选项，一般直接传入application:didFinishLaunchingWithOptions:的launchOptions参数即可

• 示例：
  Objective-C请参考：

  BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
  

  Swift请参考：

  let config = BDAutoTrackConfig(appID: "{{APPID}}", launchOptions:launchOptions)
  

#

SDK提供AB实验能力，并提供了一系列的方法：ABTestConfigValueForKey、ABTestConfigValueSyncForKey:key:defaultValue、abVidsSync、allAbVids、allABTestConfigsSync。

开启AB实验 #

使用功能，需要在 SDK 初始化设置时开启相应参数：
Objective-C请参考：

//开启ab测试，默认为YES
config.abEnable = YES; 

Swift请参考：

//开启ab测试，默认为true
config.abEnable = true;

SDK在初始化后会向分流服务发送一个分流请求（request），在获取到分流服务的响应（response）后，客户端开发可以根据分流的结果参数完成代码分支。

AB实验配置的值需要在BDAutoTrackNotificationABTestSuccess通知之后才能获取正确的值，否则可能获取不到值。 注意：在初始化之前设置好回调，再调用初始化。
成功拉取实验参数时的回调方法：

#import <RangersApplog/BDAutoTrack.h>
#import <RangersAppLog/BDAutoTrackNotifications.h>

// 设置监听
[[NSNotificationCenter defaultCenter] addObserver:self
                                        selector:@selector(onABTestSuccess:)
                                            name:BDAutoTrackNotificationABTestSuccess object:nil];

// 在回调成功后获取实验参数
- (void)onABTestSuccess:(NSNotification *)noti {
    NSLog(@"%@",noti.userInfo);
    // 这里的意思是，回调成功后，可以开始获取值
    NSNumber newColor = [BDAutoTrack ABTestConfigValueForKey:@"btnColor" defaultValue:@(0)];
    if(newColor == 0){
        // A 版本分支
    } else {
        // B 版本分支
    }
}

ABTestConfigValueForKey、ABTestConfigValueSyncForKey #

• 作用：获取AB实验的配置值，在初始化之后设置才能调用。

• 定义：

  • • (nullable id)ABTestConfigValueForKey:(NSString *)key defaultValue:(nullable id)defaultValue
  • • (nullable id)ABTestConfigValueSyncForKey:(NSString *)key defaultValue:(nullable id)defaultValue

• 参数：

  参数名	类型	必填	说明
  key	NSString	是	AB实验配置的key
  defaultValue	id	是，可nil	默认值，如果没有配置，或者未开启AB实验则返回默认值

• 示例：
  Objective-C请参考：

  [BDAutoTrack ABTestConfigValueForKey:@"btnColor" defaultValue:@(0)];
  [BDAutoTrack ABTestConfigValueSyncForKey:@"btnColor" defaultValue:@(0)];
  

  Swift请参考：

  BDAutoTrack.abTestConfigValue(forKey: "btnColor", defaultValue: 0)
  BDAutoTrack.abTestConfigValueSync(forKey: "btnColor", defaultValue: 0)
  

abVids、abVidsSync #

• 作用：获取已曝光的AB实验配置的vids，在初始化之后设置才能调用。

• 定义：

  • • (nullable NSString *)abVids
  • • (nullable NSString *)abVidsSync

• 示例：
  Objective-C请参考：

  [BDAutoTrack abVids];
  [BDAutoTrack abVidsSync];
  

  Swift请参考：

  BDAutoTrack.abVids()
  BDAutoTrack.abVidsSync()
  

allAbVids、allAbVidsSync #

• 作用：获取AB实验配置的所有vids，在初始化之后设置才能调用。

• 定义：

  • • (nullable NSString *)allAbVids
  • • (nullable NSString *)allAbVidsSync

• 示例：
  Objective-C请参考：

  [BDAutoTrack allAbVids];
  [BDAutoTrack allAbVidsSync];
  

  Swift请参考：

  BDAutoTrack.allAbVids()
  BDAutoTrack.allAbVidsSync()
  

allABTestConfigs、allABTestConfigsSync #

• 作用：获取AB实验的所有配置项，在初始化之后设置才能调用。

• 定义：

  • • (nullable NSDictionary *)allABTestConfigs
  • • (nullable NSDictionary *)allABTestConfigsSync

• 示例：
  Objective-C请参考：

  [BDAutoTrack allABTestConfigs];
  [BDAutoTrack allABTestConfigsSync];
  

  Swift请参考：

  BDAutoTrack.allABTestConfigs()
  BDAutoTrack.allABTestConfigsSync()
  

setExternalABVersion #

• 作用：设置额外的vids。如果要清空上次设置，直接传nil；每次设置都会覆盖上次设置。

• 定义：+ (void)setExternalABVersion:(nullable NSString *)versions

• 参数：

  参数名	类型	必填	说明
  versions	NSString	是，可nil	格式比如 @"1,2,3"。是逗号（英文）分割，逗号之间是数字。

• 示例：
  Objective-C请参考：

  [BDAutoTrack setExternalABVersion:@"1111,2222,3333"];
  

  Swift请参考：

  BDAutoTrack.setExternalABVersion("1111,2222,3333")
  

pullABTestConfigs #

该方法要求6.7.0以上版本。正常冷启动、切换用户、定时10分钟会自动请求AB实验配置。

• 作用：手动触发拉取AB实验配置请求。如果想实时拉取实验分流结果，可以通过该方法手动触发实验配置更新 ，注意：10秒内多次调用只会触发一次请求。获取成功后会发送BDAutoTrackNotificationABTestSuccess通知。

• 定义：+ (void)pullABTestConfigs

• 示例：
  Objective-C请参考：

  [BDAutoTrack pullABTestConfigs];
  

  Swift请参考：

  BDAutoTrack.pullABTestConfigs()
  

提供设置用户属性能力，并提供了一系列的方法：profileSet、profileSetOnce、profileUnset、profileIncrement、profileAppend。

profileSet #

• 作用：设置用户属性，存在则覆盖，不存在则创建。

• 定义：+ (void)profileSet:(NSDictionary *)profileDict

• 参数：

  参数名	类型	必填	说明
  profileDict	NSDictionary	是	参数字典的值只能是以下类型：字符串、整型、浮点型、字符串数组

• 示例：
  Objective-C请参考：

  NSDictionary *profileDict = @{@"key": @("value")};
  [BDAutoTrack profileSet:profileDict];
  

  Swift请参考：

  let profileDict: [AnyHashable: Any] = [
      "key": "value"
  ]
  BDAutoTrack.profileSet(profileDict)
  

profileSetOnce #

• 作用：设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。与profileSet接口不同的是：若某profile已成功通过profileSetOnce接口设置，那么对该profile再次调用profileSetOnce接口无效。

• 定义：+ (void)profileSetOnce:(NSDictionary *)profileDict

• 参数：

  参数名	类型	必填	说明
  profileDict	NSDictionary	是	参数字典的值只能是以下类型：字符串、整型、浮点型、字符串数组

• 示例：
  Objective-C请参考：

  NSDictionary *profileDict = @{@"key_once": @("value_once")};
  [BDAutoTrack profileSetOnce:profileDict];
  

  Swift请参考：

  let profileDict: [AnyHashable: Any] = [
      "key_once": "value_once"
  ]
  BDAutoTrack.profileSetOnce(profileDict)
  

profileIncrement #

• 作用：设置数值类型的属性，可进行累加。

• 定义：+ (void)profileIncrement:(NSDictionary <NSString *, NSNumber *> *)profileDict

• 参数：

  参数名	类型	必填	说明
  profileDict	NSDictionary	是	只能自增整数（可以为负整数）。如果传入浮点数，SDK将忽略。

• 示例：
  Objective-C请参考：

  [BDAutoTrack profileIncrement:@{@"key": @(1)}];
  

  Swift请参考：

  let profileDict: [AnyHashable: Number] = [
      "key": 1
  ]
  BDAutoTrack.profileIncrement(profileDict)
  

profileAppend #

• 作用：设置List类型的用户属性，可持续向List内添加。

• 定义：+ (void)profileAppend:(NSDictionary *)profileDict

• 参数：

  参数名	类型	必填	说明
  profileDict	NSDictionary	是	参数字典的值只能为字符串或者字符串数组。

• 示例：
  Objective-C请参考：

  [BDAutoTrack profileAppend:@{
      @"key": @[@"value_append"]
  }];
  

  Swift请参考：

  BDAutoTrack.profileAppend([["key"]:["value_append"]])
  

profileUnset #

• 作用：删除用户的属性。

• 定义：+ (void)profileUnset:(NSString *)profileName

• 参数：

  参数名	类型	必填	说明
  profileName	NSString	是	要unset的profile的名称

• 示例：
  Objective-C请参考：

  [BDAutoTrack profileUnset:@"key"];
  

  Swift请参考：

  BDAutoTrack.profileUnset("key")
  

开启元素曝光功能 #

引入模块 #

引入Exposure子模块，subspecs添加 Exposure

pod 'RangersAppLog', 'SDK-VERSION', 
    :subspecs => [
        # ...
        'Exposure'
    ]

头文件引入 #

//相关的功能设置引入头文件
//modular方式集成 @import RangersAppLog;
#import <RangersAppLog/BDAutoTrackExposure.h>

开启功能 #

使用功能，需要在 SDK 初始化设置时开启相应参数：
Objective-C请参考：

// 全局功能控制开关 YES|NO. 默认为开启
config.exposureEnabled = YES; 

Swift请参考：

// 全局功能控制开关 YES|NO. 默认为开启
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)

功能调试 #

开启可视化调试功能后，对组件曝光功能进行调试。

• 开启监控曝光的组件，生成红色的边框。
• 组件触发曝光，生成半透明的浮层。

Objective-C 请参考：

[config.exposureConfig enableVisualDiagnosis:YES];

Swift 请参考：

config.exposureConfig.enableVisualDiagnosis(true)