You need to enable JavaScript to run this app.
最新活动
产品
解决方案
定价
生态与合作
支持与服务
开发者
了解我们
导航
A/B测试
  • 文档首页
    • /
  • A/B测试

iOS SDK集成开发指南

最近更新时间：2023.07.24 19:00:49

首次发布时间：2021.02.23 10:41:55

我的收藏
一、 概述

「A/B 测试」 在 Android 客户端的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.15.3', 
    :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。如特殊情况需要手动引入，请阅读本小节。

iOSSDK下载SDK版本MD5文件

增长营销套件SDK下载

6.15.3

e01c2887a4293a8400d2b954f54e5a35

RangersAppLog@6.15.3.zip
15.10MB

将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. 初始化SDK

说明

SDK会在初始化的时候就采集客户信息，请确保您采集用户信息之前已经得到用户的授权，建议的操作如下：

  1. 授权后再初始化SDK，授权前所有的信息都不会采集，一些预置事件也不会被采集；

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 = 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 startTrackWithConfig:config];
    /* 初始化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.start(with: config)
        /* 初始化SDK结束 */  
        return true
    }

2.3.2 私有化版本

如您使用私有化部署版本，请参照如下代码初始化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 startTrackWithConfig:config];
    /* 初始化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.start(with: config)
        /* 初始化SDK结束 */  
        return true
    }

2.3.3 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 startTrackWithConfig:config];
    /* 初始化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.start(with: config)
        /* 初始化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()

3. 配置Scheme(可选)

如需使用实时实时埋点检测或圈选功能，请引入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
}
4. 初始化基本配置

以下为常用的初始化基本配置，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页全埋点事件。

注意

⚠️请注意，此开关的使用无需在h5页内集成js sdk，且与js sdk全埋点功能独立无关联。

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. 用户与用户属性

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")
6. 获取实验参数

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
7. 事件与事件属性（上报实验指标）

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. 获取平台ID与通知

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 增长分析-火山引擎



一、 概述

二、集成说明

1. 集成SDK

1.1 使用CocoaPods引入source源

1.2 引入SDK

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

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

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

1.6 手动引入须知

2. 初始化SDK

2.1 获取appid

2.2 获取数据上送地址

2.3 初始化SDK

2.3.1 SaaS版本

2.3.2 私有化版本

2.3.3 SaaS云原生版本

2.4 多实例初始化(可选)

3. 配置Scheme(可选)

3.1 获取URL Scheme

3.2 添加URL Scheme

3.3 重写回调方法

4. 初始化基本配置

4.1 全埋点设置开关

4.2 开启圈选埋点

4.3 查看日志打印

4.4 AB设置开关

4.5 加密设置开关

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

4.6 设置APP Language 和 APP Region

4.7 打通内嵌H5页

4.8 原生端采集H5全埋点

4.9 关闭设备IDFA、IDFV采集

5. 用户与用户属性

5.1 登录态变化调用

5.1.1 账户登录

5.1.2 账户登出

5.2 设置用户属性

5.2.1 profileSet

5.2.2 profileSetOnce

5.2.3 profileIncrement

5.2.4 profileAppend

5.2.5 profileUnset

6. 获取实验参数

7. 事件与事件属性（上报实验指标）

2.1 上报代码埋点

2.2 事件公共属性

2.2.1 设置公共属性

2.2.2 移除公共属性

8. 获取平台ID与通知

8.1 获取平台生成ID

8.2 获取SDK版本号

8.3 获取各类通知

三、常见问题