iOS SDK集成开发指南

「A/B 测试」 在 iOS 客户端的SDK 使用的为增长营销套件SDK ，主要的和A/B Test 相关接口有两个：

• 实验组分流接口
• 指标上报（事件埋点上报）接口

1. 集成SDK

1.1 使用CocoaPods引入source源

在Podfile中，添加source源。

source 'https://github.com/volcengine/volcengine-specs.git'

1.2 引入SDK

在Podfile中，引入SDK，并执行pod install --repo-update更新Pods。

pod 'RangersAppLog', '6.16.6', 
    :subspecs => [
        'Host/CN', #SaaS版本需引入，私有化版本无需引入
        'Core',
        'Encryptor/VOLC',
        'UITracker',
        'Log', #无需圈选和实时埋点检测可以移除，参考1.3节
        'Picker', #无需圈选功能可以移除，参考4.2节
        'Unique' #用于在授权后采集IDFA，无需采集可以移除，参考4.8节
    ]

1.3 引入调试工具 -DevTools组件(可选)

6.12.0+ 支持
开发调试阶段集成，请勿带入线上环境

DevTools是辅助开发者或测试人员进行应用内埋点验证和SDK接入问题排查的组件，详细接入文档请查阅：DevTools-iOS 快速接入。

• SDK subspecs 添加 DevTools

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

• 开启相关功能

#import <RangersAppLog/BDAutoTrackDevTools.h>
//配置开启DevTool功能
config.devToolsEnabled = YES;

//在BDAutoTrack 初始化之后添加方法 显示悬浮按钮入口
[BDAutoTrackDevTools showFloatingEntryButton];

1.4 实时埋点检测和圈选功能(可选)

如需使用实时埋点检测或圈选功能，请引入Log子库。 否则可跳过此步骤。
请注意，除引入子库外，您还需要完成下文3.配置Scheme的步骤。

1.5 反作弊风控子库(可选)

如需使用广告监测功能，为使其反作弊识别准确度更高，请额外引入VolMetaSecML风控子库。否则可跳过此步骤。

pod 'VolMetaSecML', '[4.3.0.5](http://4.3.0.5)-bugfix' #反作弊风控子库

1.6 手动引入须知

推荐您通过CocoaPods引入SDK。如特殊情况需要手动引入，请阅读本小节。

将RangersAppLog文件夹下的所有文件复制到项目文件夹下，并在xcode中依次添加到项目中。添加依赖：

• libz.tbd
• libsqlite3.tbd
• CoreGraphics.framework
• Security.framework
• CoreTelephony.framework (读取运营商名称)
• SystemConfiguration.framework (判断网络状态)
• JavaScriptCore.framework
• WebKit.framework
• AdSupport.framework (不使用全埋点或圈选功能就不需要依赖)
• AppTrackingTransparency.framework (不集成Unique模块不需要依赖)

同时需要添加编译项 other linker flags，如下图：

• -ObjC
• 或者-force_load $(PROJECT_DIR)/yourpath/RangersAppLog.framework/Versions/A/RangersAppLog

注意：如果使用手动引入sdk方式，在下方import文件时需要配置header search，配置完直接引入文件即可。
例如：

#import "BDAutoTrack.h"

2.1 获取appid

在开始集成前，首先需要在集团中拥有一个应用，请参考：如何创建应用。
「应用列表」-> 接入应用的「详情」->「应用ID」中可查看您的appid。

2.2 获取数据上送地址

私有化部署版本需要获取数据上送地址。
如您不清楚此地址，请联系您的项目经理或客户成功经理。

2.3 初始化SDK

2.3.1 SaaS云原生版本

如您使用Saas云原生部署版本，请参照如下代码初始化SDK，初始化代码必须在主线程执行。 Objective-C请参考：

#import <RangersAppLog/BDAutoTrack.h>
#import <RangersAppLog/BDAutoTrackConfig.h>
#import <RangersAppLog/BDAutoTrackURLHostItemCN.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    /* 初始化SDK开始 */
    // 参数APPID: 参考2.1节获取
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = @"App Store"; 

    // 设置数据上送地址
    config.serviceVendor = BDAutoTrackServiceVendorPrivate;
    BDAutoTrackRequestHostBlock block =
        ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
            if (requestURLType == BDAutoTrackRequestURLABTest) {
                return @"https://tab.volces.com";
            }
            return @"https://gator.volces.com";
        };
    [BDAutoTrack setRequestHostBlock:block];
    
    config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
    config.abEnable = YES; //开启ab测试，默认为YES
    config.showDebugLog = NO; // YES:开启日志，需要参考4.3设置Logger，NO:关闭日志
    config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭
    config.clearABCacheOnUserChange = YES;//默认切换用户重新获取A/B配置信息，如果要关闭则把clearABCacheOnUserChange配置项置为NO
    // 如果需要设置当前登陆态 since 6.13.0+
    // [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"当前登陆态UUID" withType:@"uuid_type"]; 
    [BDAutoTrack sharedTrackWithConfig:config]; //SDK初始化
    /* 初始化SDK结束 */
    
    [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 

• Swift

import RangersAppLog
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        /* 初始化SDK开始 */
        // 参数APPID: 参考2.1节获取
        let config = BDAutoTrackConfig(appID: "{{APPID}}")
        // 设置渠道，iOS一般默认App Store渠道
        config.channel = "App Store"
        
        // 设置数据上送地址
        BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in
            if (requestURLType == BDAutoTrackRequestURLABTest) {
                return "https://tab.volces.com"
            }
            return "https://gator.volces.com"
        }
        
        config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭
        config.abEnable = true; //开启ab测试，默认为true
        config.showDebugLog = false // true:开启日志，需要参考4.3设置Logger，false:关闭日志
        config.logNeedEncrypt = true // 加密开关，true开启，false关闭
        config.clearABCacheOnUserChange = true//默认切换用户重新获取A/B配置信息，如果要关闭则把clearABCacheOnUserChange配置项置为false
        // 如果需要设置当前登陆态 since 6.13.0+
        // BDAutoTrack.shared().setCurrentUserUniqueID("uuid", withType: "uuidtype")
        BDAutoTrack.sharedTrack(with: config)
        /* 初始化SDK结束 */  
        
        BDAutoTrack.shared().start() //SDK启动
        return true
    }

2.3.2 SaaS-非云原生版本（旧版）

如您使用SaaS部署版本，请参照如下代码初始化SDK。
Objective-C请参考：

#import <RangersAppLog/BDAutoTrack.h>
#import <RangersAppLog/BDAutoTrackConfig.h>
#import <RangersAppLog/BDAutoTrackURLHostItemCN.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    /* 初始化SDK开始 */
    // 参数APPID: 参考2.1节获取
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = @"App Store"; 
    // 设置数据上送地址
    config.serviceVendor = BDAutoTrackServiceVendorCN;
    config.abEnable = YES; //开启ab测试，默认为YES
    config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
    config.showDebugLog = NO; // YES:开启日志，需要参考4.3设置Logger，NO:关闭日志
    config.clearABCacheOnUserChange = YES;//默认切换用户重新获取A/B配置信息，如果要关闭则把clearABCacheOnUserChange配置项置为NO
    config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭
    [BDAutoTrack sharedTrackWithConfig:config]; //SDK初始化
    /* 初始化SDK结束 */
    
    [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 

Swift请参考：

import RangersAppLog
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        /* 初始化SDK开始 */
        // 参数APPID: 参考2.1节获取
        let config = BDAutoTrackConfig(appID: "{{APPID}}")
        // 设置渠道，iOS一般默认App Store渠道
        config.channel = "App Store"
        // 设置数据上送地址
        config.serviceVendor = BDAutoTrackServiceVendor.CN
        config.abEnable = true //开启ab测试，默认为true
        config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭
        config.showDebugLog = false // true:开启日志，需要参考4.3设置Logger，false:关闭日志
        config.clearABCacheOnUserChange = true //默认切换用户重新获取A/B配置信息，如果要关闭则把clearABCacheOnUserChange配置项置为false
        config.logNeedEncrypt = true // 加密开关，true开启，false关闭
        BDAutoTrack.sharedTrack(with: config)
        /* 初始化SDK结束 */  
        
        BDAutoTrack.shared().start() //SDK启动
        return true
    }

2.3.3 私有化版本

如您使用私有化部署版本，请参照如下代码初始化SDK。
Objective-C请参考：

#import <RangersAppLog/BDAutoTrack.h>
#import <RangersAppLog/BDAutoTrackConfig.h>
#import <RangersAppLog/BDAutoTrackURLHostItemCN.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    /* 初始化SDK开始 */
    // 参数APPID: 参考2.1节获取
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = @"App Store"; 
    
    // 设置私有化部署数据上送地址，参考2.2节获取，{{REPORT_URL}} 例如 https://yourdomain.com，注意域名后不要加“/”
    config.serviceVendor = BDAutoTrackServiceVendorPrivate;
    BDAutoTrackRequestHostBlock block =
        ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
            return @"{{REPORT_URL}}";
        };
    [BDAutoTrack setRequestHostBlock:block];
    config.abEnable = YES; //开启ab测试，默认为YES
    config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
    config.showDebugLog = NO; // YES:开启日志，需要参考4.3设置Logger，NO:关闭日志
    config.clearABCacheOnUserChange = YES;//默认切换用户重新获取A/B配置信息，如果要关闭则把clearABCacheOnUserChange配置项置为NO
    config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭
    [BDAutoTrack sharedTrackWithConfig:config]; //SDK初始化
    /* 初始化SDK结束 */
    
    [[BDAutoTrack sharedTrack] startTrack]; //SDK启动 

Swift请参考：

import RangersAppLog
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        /* 初始化SDK开始 */
        // 参数APPID: 参考2.1节获取
        let config = BDAutoTrackConfig(appID: "{{APPID}}")
        // 设置渠道，iOS一般默认App Store渠道
        config.channel = "App Store"
        
        // 设置私有化部署数据上送地址，参考2.2节获取，{{REPORT_URL}} 例如 https://yourdomain.com，注意域名后不要加“/”
        BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in
            return "{{REPORT_URL}}"
        }
        config.abEnable = true //开启ab测试，默认为true
        config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭
        config.showDebugLog = false // true:开启日志，需要参考4.3设置Logger，false:关闭日志
        config.clearABCacheOnUserChange = true//默认切换用户重新获取A/B配置信息，如果要关闭则把clearABCacheOnUserChange配置项置为false
        config.logNeedEncrypt = true // 加密开关，true开启，false关闭
        BDAutoTrack.sharedTrack(with: config)
        /* 初始化SDK结束 */  
        
        BDAutoTrack.shared().start() //SDK启动
        return true
    }

2.4 多实例初始化(可选)

多实例初始化，指SDK支持在同包名的App中向多个应用(多个appid)开启埋点，且埋点数据相互隔离，每一个appid对应一个单独的实例。使用场景例如：

• 第三方SDK依赖 增长营销套件SDK 做SDK内部产生的埋点时；
• 同一个App或系统中，关联多个埋点应用(多个appid)，共用 增长营销套件SDK 时。

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()

如需使用实时实时埋点检测或圈选功能，请引入Log子库。 否则可跳过此步骤。 请注意，除引入子库外，您还需要完成下文3.配置Scheme的步骤。

3.1 获取URL Scheme

「应用列表」-> 接入应用的「详情」->「URL Scheme」中可查看您的scheme，一般为rangersapplog.xxxxx的形式。

3.2 添加URL Scheme

把URL Scheme添加到您的项目中。

3.3 重写回调方法

请根据需要使用实时埋点检测或圈选事件功能的设备版本，并添加URL的处理。
如您使用iOS 13以下的设备，则重写UIApplicationDelegate的回调方法。

#import <RangersAppLog/BDAutoTrackSchemeHandler.h>
- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options {
    // 参数APPID: 参考2.1节获取
    if ([[BDAutoTrackSchemeHandler sharedHandler] handleURL:url appID:@"appid" scene:nil]) {
        return YES;
    }
    // ……
    return NO;
}

如您使用iOS 13 及以上的设备，请重写UISceneDelegate的回调方法。
Objective-C请参考：

#import <RangersAppLog/BDAutoTrackSchemeHandler.h>
- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {
    for (UIOpenURLContext *context in URLContexts) {
        NSURL *URL = context.URL;
        // 参数APPID: 参考2.1节获取
        if ([[BDAutoTrackSchemeHandler sharedHandler] handleURL:URL appID:@"{{APPID}}" scene:scene]) {
            continue;
        }
        /// ……
    }
}

Swift请参考：

import RangersAppLog
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {  
    // 参数APPID: 参考2.1节获取
    if(BDAutoTrackSchemeHandler.shared().handle(url, appID: "{{APPID}}", scene: nil)) {
       return true
    }      
    return false
}

以下为常用的初始化基本配置，config 均指初始化时的BDAutoTrackConfig。

4.1 全埋点设置开关

Objecetive-C请参考：

// 开启全埋点事件的上送
config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭

Swift请参考：

// 开启全埋点事件的上送
config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭

4.2 开启圈选埋点

在1.2节的引入中，引入Picker子库即开启圈选埋点。相反，移除Picker子库即关闭圈选埋点。

4.3 查看日志打印

Objecetive-C请参考：

// 在控制台输出日志，可用于观察用户行为日志上报情况，建议在上线时关闭
config.showDebugLog = NO; // YES:开启日志，NO:关闭日志
config.logger = ^(NSString * _Nullable log) {NSLog(@"%@",log);}; // 开启日志时设置Logger

Swift请参考：

// 在控制台输出日志，可用于观察用户行为日志上报情况，建议在上线时关闭
config.showDebugLog = false // true:开启日志，false:关闭日志
config.logger = { (log) inprint(log ?? "log is nil")} // 开启日志时设置Logger

4.4 AB设置开关

Objecetive-C请参考：

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

Swift请参考：

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

4.5 加密设置开关

加密设置默认开启。您可在debug阶段关闭加密，以便于抓包联调。
Objecetive-C请参考：

// 加密设置开关，线上版本建议开启
config.logNeedEncrypt = YES; // YES:打开加密，NO:关闭加密

Swift请参考：

// 加密设置开关，线上版本建议开启
config.logNeedEncrypt = true // true:打开加密，false:关闭加密

4.5 切换用户清空AB信息开关

Objecetive-C请参考：

//默认切换用户重新获取A/B配置信息，如果要关闭则把clearABCacheOnUserChange配置项置为NO
config.clearABCacheOnUserChange = YES;

Swift请参考：

//默认切换用户重新获取A/B配置信息，如果要关闭则把clearABCacheOnUserChange配置项置为false
config.clearABCacheOnUserChange = true

4.6 设置APP Language 和 APP Region

Objecetive-C请参考：

// 修改语言和地区，设置APP Language 和 APP Region
[BDAutoTrack setAppLauguage:@"zh/en/jp/fr"];
[BDAutoTrack setAppRegion:@"cn"];

Swift请参考：

// 修改语言和地区，设置APP Language 和 APP Region
BDAutoTrack.setAppLauguage("zh/en/jp/fr")
BDAutoTrack.setAppRegion("cn")

4.7 打通内嵌H5页

开启内嵌H5页打通后，内嵌H5页上产生的事件将通过iOS SDK上报，不在js SDK上报，并复用iOS端设置的user_unique_id和公共属性。
请注意，打通功能还需在H5页上集成js sdk，并开启js的打通开关，请参考Web/JS SDK 集成 3.6节。
Objecetive-C请参考：

// 开启内嵌H5打通开关
config.enableH5Bridge = YES;

Swift请参考：

// 开启内嵌H5打通开关
config.enableH5Bridge = true;

开关开启后，必须配置打通白名单。仅白名单内配置的域名生效打通，白名单可用通配符方式添加，*表示通配符。
Objecetive-C请参考：

// 内嵌H5页白名单配置
// 示例：如需打通 www.volcengine.com 和 www.bytedance.com 两个H5页
config.H5BridgeAllowedDomainPatterns = @[@"www.volcengine.com",@"*.bytedance.*"];

// 适配 www.bytedance.com 的白名单有多种，请根据业务场景配置白名单，例如：
// www.bytedance.com 或 *.bytedance.* 或 *.*.* 均可实现。

Swift请参考：

// 内嵌H5页白名单配置
// 示例：如需打通 www.volcengine.com 和 www.bytedance.com 两个H5页
config.h5BridgeAllowedDomainPatterns = ["[www.volcengine.com](http://www.volcengine.com/)", "*.bytedance.*"]

4.8 原生端采集H5全埋点

原生端内嵌webview页时，通过打开以下开关，可从原生端全埋点事件采集h5页全埋点事件。

Objecetive-C请参考：

//内嵌H5页面的全埋点事件
config.H5AutoTrackEnabled = YES; // YES:开启h5全埋点事件，NO:关闭h5全埋点事件

Swift请参考：

//内嵌H5页面的全埋点事件
config.H5AutoTrackEnabled = true; // true:开启h5全埋点事件，false:关闭h5全埋点事件

4.9 关闭设备IDFA、IDFV采集

设备IDFA、IDFV的采集通过Unique子库完成。在1.2节的引入SDK中，引入Unique子库即开启采集，移除Unique子库即关闭采集。

注意：

上报事件和属性前，请先阅读数据格式（数据格式）介绍。

5.1 登录态变化调用

5.1.1 账户登录

如您的产品中有账户体系，请在用户登录后立即设置uuid，以保证用户登录前后口径一致性。
Objective-C请参考：

#import <RangersAppLog/RangersAppLog.h>
// 设置您账号体系的ID, 并保证其唯一性
[BDAutoTrack setCurrentUserUniqueID:@"{{USER_UNIQUE_ID}}"];

Swift请参考：

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

如您在初始化SDK时，已获取到可设置的uuid，例如已登录的用户，请在初始化时调用设置。初始化后无需再次调用重复设置。
Objective-C请参考：

// 初始化时设置uuid
config.initialUserUniqueID = @"{{USER_UNIQUE_ID}}";

Swift请参考：

// 初始化时设置uuid
config.initialUserUniqueID = "{{USER_UNIQUE_ID}}"

5.1.2 账户登出

在账户登出时调用。
Objective-C请参考：

[BDAutoTrack clearUserUniqueID];

Swift请参考：

BDAutoTrack.clearUserUniqueID();

5.2 设置用户属性

5.2.1 profileSet

设置用户属性，存在则覆盖，不存在则创建。
Objective-C请参考：

// 示例：设置用户属性，属性名为key，属性值为value
NSDictionary *profileDict = @{@"key": @("value")};
[BDAutoTrack profileSet:profileDict];

Swift请参考：

// 示例：设置用户属性，属性名为key，属性值为value
let profileDict: [AnyHashable: Any] = [
    "key": "value"
]
BDAutoTrack.profileSet(profileDict)

5.2.2 profileSetOnce

设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。
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)

5.2.3 profileIncrement

设置数值类型的属性，可进行累加。
Objective-C请参考：

// 示例：设置用户属性，属性名为key，属性值为1
[BDAutoTrack profileIncrement:@{@"key": @(1)}];

Swift请参考：

// 示例：设置用户属性，属性名为key，属性值为1
let profileDict: [AnyHashable: Number] = [
    "key": 1
]
BDAutoTrack.profileIncrement(profileDict)

5.2.4 profileAppend

设置List类型的用户属性，可持续向List内添加。
Objective-C请参考：

// 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append
[BDAutoTrack profileAppend:@{
    @"key": @[@"value_append"]
}];

Swift请参考：

// 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append
BDAutoTrack.profileAppend([["key"]:["value_append"]])

5.2.5 profileUnset

删除用户的属性。
Objective-C请参考：

// 示例：删除用户属性，属性名为key
[BDAutoTrack profileUnset:@"key"];

Swift请参考：

// 示例：删除用户属性，属性名为key
BDAutoTrack.profileUnset("key")

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

• 请注意此步骤的前置条件：已经根据实验的需求方创建好了实验及相关的参数，具体见“创建实验”。
• 请注意每次调用ABTestConfigValueForKey时,会默认上报一条曝光事件 abtest_exposure

ABTest的值需要在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 版本分支    
    }
}
objective-c

Sync方法，是可以阻塞等待本地缓存文件的读取 此方法旨在便于业务在初始化后立即获取到已缓存的AB实验数据，可能耗时较长。

/*! @abstract 本地缓存已加载时同`ABTestConfigValueForKey:defaultValue:`。本地缓存未加载时将阻塞等待其加载完成。
 @discussion 本地缓存一般在初始化后30-100ms内加载完成。
 */
- (nullable id)ABTestConfigValueSyncForKey:(NSString *)key defaultValue:(nullable id)defaultValue;
- (nullable NSString *)abVidsSync;
- (nullable NSString *)allAbVids;
- (nullable NSDictionary *)allABTestConfigsSync;

如果想实时拉取实验分流结果，可以通过 pullABTestConfigs 方法手动触发实验配置更新 (10秒内多次调用只会触发一次请求)

[BDAutoTrack pullABTestConfigs];//此功能需要6.7.0以上版本
// 获取成功后会发送 BDAutoTrackNotificationABTestSuccess 通知
// A BDAutoTrackNotificationABTestSuccess notification will be received 
// if the test configs are correctly pulled

2.1 上报代码埋点

用户行为日志采用事件event+属性params的形式，事件一般对应多个属性，也可以仅有事件没有属性。代码埋点方案一般由数据分析师或产品运营设计。
仅上报事件的代码埋点，示例如下：
Objective-C请参考：

// 示例：上报事件event，该事件不包含属性
// 置于业务逻辑对应位置
[BDAutoTrack eventV3:@"event" params: NULL];

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])

2.2 事件公共属性

如需在每个事件中都包括某属性，可通过公共属性设置，无需在每个事件中重复设置。公共属性只需设置一次，即可包括在所有代码埋点事件、预置事件和全埋点事件中。

2.2.1 设置公共属性

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"]
}

2.2.2 移除公共属性

Objective-C请参考：

// 示例：移除属性名为key_public的公共属性
[BDAutoTrack removeCustomHeaderValueForKey:@"key_public"];

Swift请参考：

// 示例：移除属性名为key_public的公共属性
BDAutoTrack.removeCustomHeaderValueForKey("key_public");

8.1 获取平台生成ID

Objective-C请参考：

#import <RangersApplog/BDAutoTrackNotifications.h>
// 在初始化 sdk 之前设置监听
 [[NSNotificationCenter defaultCenter] addObserver:self
                                            selector:@selector(onRegisterSuccess:)
                                                name:BDAutoTrackNotificationRegisterSuccess object:nil];
//SDK 初始化代码部分
//然后在 SDK 初始化之后设置回调
- (void)onRegisterSuccess:(NSNotification *)noti  {
    // 请在初始化完成的3秒后开始获取，否则可能返回为空
    NSString *dids = [noti.userInfo objectForKey:kBDAutoTrackNotificationRangersDeviceID];
    NSString *ssids = [noti.userInfo objectForKey:kBDAutoTrackNotificationSSID]; 
    NSLog(@"onRegisterSuccess.dids：%@", dids); // 获取设备bddid
    NSLog(@"onRegisterSuccess.ssids：%@", ssids); // 获取SSID
}

Swift请参考：

// 请在初始化完成的3秒后开始获取，否则可能返回为空
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)")
}

8.2 获取SDK版本号

Objective-C请参考：

// SDK版本号格式为X.X.X
[BDAutoTrack sdkVersion]

Swift请参考：

BDAutoTrack.sdkVersion()

8.3 获取各类通知

SDK提供方法用以获取各类通知。各通知在BDAutoTrackNotifications.h头文件中均有描述。

// SDK 注册成功通知 
BDAutoTrackNotificationRegisterSuccess
//SDK 注册请求失败通知 
BDAutoTrackNotificationRegisterFailure
// 激活成功通知 
BDAutoTrackNotificationActiveSuccess
// SDK ABTest配置拉取成功通知 
BDAutoTrackNotificationABTestSuccess
// SDK ABTestVid发生变化时候的通知 
BDAutoTrackNotificationABTestVidsChanged

1、当我需要创建客户端实验，但是想要关注服务端事件相关的指标，需要怎么上报服务端事件才能正常查看实验报告?

• 获取全部的实验 id

NSString *ab = [BDAutoTrack allAbVids];
NSLog(@"allAbVids：%@",ab);

//返回值示例：14320,14338，代表进入了两个实验
objective-c

• 传给服务端
• 调用http接口上报服务端事件时，需要在事件里带上客户端实验信息(ab_sdk_version)，具体事件上报格式参考HTTP API 增长分析-火山引擎