事件、事件属性、事件公共属性、用户属性

DataFinder 的用户行为数据分析是基于事件+用户模型的分析模型。

• 事件&事件属性：用户的某一种或一类行为称之为“事件”，事件属性即事件触发时同步采集的事件发生的形式、位置等用来描述事件的信息。例如，某个用户购买了某个商品，则该用户的行为事件为“购买”，事件属性为“商品名称”、“商品分类”、“支付金额”等。
• 事件公共属性：指不与某个事件强关联、在多个或所有事件中都共同存在的不频繁变化的属性，例如，应用的版本号、设备信息等。
• 用户&用户属性：用户指的是事件行为的发生主体人。用户属性指的是用户自身状态的属性（与行为无关，例如年龄、性别等）或与行为有关但不常变化的用户相关属性（如 VIP 等级、注册时间等）。

您需根据业务分析需要，规划好待采集的事件、事件属性、用户属性有哪些、类型是什么，进行 SDK 集成时

详细概念介绍请参见数据模型。

埋点、全埋点、自定义埋点

• 埋点：通过 SDK 的开发，将事件逻辑写入代码的过程，称之为埋点。DataFinder 为您提供了预置事件及事件属性，这类事件及事件属性无需您手动埋点，只需打开采集开关即可。
• 全埋点：是 DataFinder 提供的预置事件和事件属性的一种，在 DataFinder 中，采集的全埋点事件为 bav2b_click 按钮点击， bav2b_page 页面浏览。不需要研发额外投入，但会以上报大量数据为代价，并且只可以采集简单的 PV、UV，对于丰富业务数据的采集显得有些‘力不从心’。
• 代码埋点：代码埋点指的是开发工程师，按照业务个性化需求，人工写入代码中以实现数据采集逻辑。采集范围广、应用灵活。但需要研发投入，且需要一定的技术能力。

通常建议您结合 DataFinder 提供的预置事件/属性和自定义埋点进行埋点规划。

埋点、全埋点

header

存放事件公共属性。
app_id、os_name 这些都是预置的，会直接放在 header下，如果是您自定义设置的事件公共属性，会放到header.custom 下。

{
    "event_v3" : [
      {
        "local_time_ms" : 1749023627671,
        "$user_unique_id_type" : null,
        "params" : {
          "_additional" : "ddd",
          "send_times" : 3,
          "session_no" : 1,
          "session_start_time" : "2025-06-04 15:50:47",
          "$app_version" : "1.0",
          "current_duration" : 60
        },
        "event" : "play_session",
        "user_unique_id" : null,
        "ab_sdk_version" : "1314,1328",
        "track_id" : "E957BFFB-CF87-49E2-8F0E-305DBE8DD5C6",
        "ssid" : "fc351da8-ddff-4ae3-9878-2c380b6796e2",
        "session_id" : "803E519E-D828-48C1-8F46-2C89CA9BC90A",
        "nt" : 4,
        "datetime" : "2025-06-04 15:53:47",
        "tea_event_index" : 24
      },
      {
        "local_time_ms" : 1749023606322,
        "$user_unique_id_type" : null,
        "params" : {
          "page_title" : "导航首页",
          "referrer_page_path" : "",
          "refer_page_key" : "BDAutoTrackDevNetworkController",
          "is_back" : 1,
          "page_key" : "BDTestIntroducerViewController",
          "refer_page_title" : "网络",
          "$app_version" : "1.0",
          "_additional" : "ddd"
        },
        "event" : "bav2b_page",
        "user_unique_id" : null,
        "ab_sdk_version" : "1314,1328",
        "track_id" : "0A944C1F-5280-409C-9645-44B84E7CDBAF",
        "ssid" : "fc351da8-ddff-4ae3-9878-2c380b6796e2",
        "session_id" : "803E519E-D828-48C1-8F46-2C89CA9BC90A",
        "nt" : 4,
        "datetime" : "2025-06-04 15:53:26",
        "tea_event_index" : 23
      }
    ],
    "time_sync" : {
      "local_time" : 1749023569,
      "server_time" : 1749023569
    },
    "magic_tag" : "ss_app_log",
    "header" : {
      "app_version_minor" : "1",
      "region" : "CN",
      "access" : "WIFI",
      "os_version" : "18.4",
      "device_model" : "arm64",
      "user_unique_id_type" : null,
      "platform" : "ios",
      "app_name" : "applog_oc_demo",
      "vendor_id" : "FA190FD0-2293-4025-B8E6-A7E015CD579D",
      "sdk_version" : 61703,
      "custom" : {
        "Dictioanry" : {
          "A" : "B"
        },
        "Array" : [
          "123",
          "34"
        ],
        "level" : 0,
        "boolValue" : true,
        "intValue" : 1,
        "touch_point" : "iOS APP端"
      },
      "display_name" : "ObjCExample",
      "channel" : "App Store",
      "sdk_lib" : "ios",
      "app_region" : "CN",
      "ab_sdk_version" : "1314,1328",
      "user_agent" : "ObjCExample 1.0 rv:1 (iphone; iOS 18.4; en_CN)",
      "idfa" : "00000000-0000-0000-0000-000000000000",
      "device_platform" : "iphone",
      "install_id" : "722808630681020",
      "user_unique_id" : null,
      "os" : "iOS",
      "tz_name" : "Asia\/Shanghai",
      "tz_offset" : 28800,
      "app_language" : "en",
      "is_upgrade_user" : false,
      "aid" : "418165",
      "ssid" : "fc351da8-ddff-4ae3-9878-2c380b6796e2",
      "package" : "com.data.extracker",
      "is_jailbroken" : false,
      "language" : "zh",
      "sdk_version_code" : 10061703,
      "bd_did" : "LIDKFFMUEAV5HTDDPHFYUGDUCXKMUT7U2B3IJOD5GVACVKXUVPKQ01",
      "app_version" : "1.0",
      "resolution" : "1206*2622",
      "timezone" : 8
    },
    "local_time" : 1749023629
}

事件

存放事件及事件属性。
事件分为 launch、terminate、event_v3。
其中 launch、terminate 为预置的启动、退出事件。
event_v3 存放自定义事件、page 事件等，每个 event_v3 类型事件都有 event、params、local_time_ms、session_id 几个字段，其中local_time_ms、session_id 是SDK自动产生的，而event、params 是业务设置的，event 是事件名，params 存放的是事件属性（值是 JSON 对象进行了序列化操作）。

iOS

• SaaS-云原生（华北）：https://gator.volces.com
• SaaS-云原生（华南）：
  https://gator.uba.cn-guangzhou.volces.com

• https://gator.uba.ap-southeast-1.volces.com

• app_id：替换为上报的 app_id
• channel_domain: 'https://gator.uba.ap-southeast-1.bytepluses.com'

引入：'Host/CN' 后，无需配置

引入：'Host/SG' 后，无需配置

使用CocoaPods引入source源，在Podfile中，添加source源。

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

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

pod 'RangersAppLog', '6.17.11',
    :subspecs => [
        'Core',
        # 其他可选的子模块
        'UITracker' #全埋点功能（可选）
        # ...更多可选的子模块
    ]

Core

核心模块，必须

Host/CN

SaaS国内非云原生，可选

在SaaS国内非云原生环境下需引入这个子模块，其他环境不需要

Host/SG

SaaS海外非云原生，可选

在SaaS国外非云原生环境下需引入这个子模块，其他环境不需要

UITracker

全埋点功能，可选

需要全埋点功能时需引入这个子模块

Log

圈选功能和实时埋点检测，可选

希望进行埋点实时检测或圈选功能时，需引入这两个子模块，实时埋点检测和圈选功能仅在开发阶段使用，上线后需要移除这两个子模块

Picker

圈选功能，可选

Unique

采集IDFA，可选

希望在授权后采集IDFA，需引入这个子模块，该库仅在额外购买 Tracer 做归因业务时需要

DevTools

DevTools组件，可选

DevTools是辅助开发者或测试人员进行应用内埋点验证和SDK接入问题排查的组件

Exception

崩溃采集，可选

目前仅支持采集 NSException 崩溃

DeviceOrientation

屏幕方向采集，可选

版本6.11.0+后开始支持

Location

采集GPS，可选

需要定位权限，也可以选择手动传入经纬度坐标，从而不集成该库

Encryptor/SM2

国密SM2加密，可选

仅私有化版本支持

Exposure

组件曝光，可选

用于组件曝光事件

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

# target 'TestDemo' do
    # ...
    pod 'RangersAppLog', '6.17.11',
        :subspecs => [
            'Core',
            'UITracker' #全埋点功能（可选）
        ]
# end

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

# target 'TestDemo' do
    # ...
    pod 'RangersAppLog', '6.17.11',
        :subspecs => [
            'Core',
            'UITracker' #全埋点功能（可选）
        ]
# end

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

# target 'TestDemo' do
    # ...
    pod 'RangersAppLog', '6.17.11',
        :subspecs => [
            'Core',
            'Host/CN', # 非云原生-国内
            # 'Host/SG', # 非云原生-海外
            'UITracker' #全埋点功能（可选）
        ]
# end

以下为一个简单的初始化 SDK 代码示例，您可通过此示例来快速了解 SDK 集成时的代码、涉及的初始化接口、典型的配置参数等，后续步骤中会为您逐步介绍 SDK 集成的详细操作要点。
Objective-C请参考：

#import <RangersAppLog/BDAutoTrack.h>
#import <RangersAppLog/BDAutoTrackConfig.h>
// 若使用 Unique 子库，则需要依赖该头文件
// #import <RangersAppLog/BDAutoTrack+IDFA.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    /* 初始化SDK开始 */
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = @"App Store";

    // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址
    config.serviceVendor = BDAutoTrackServiceVendorPrivate;
    BDAutoTrackRequestHostBlock block =
        ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
            return @"https://****.****.com";
        };
    [BDAutoTrack setRequestHostBlock:block];

    config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
    config.showDebugLog = NO; // YES:开启日志，NO:关闭日志
    config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭
    [BDAutoTrack sharedTrackWithConfig:config];
    /* 初始化SDK结束 */

    // 若使用 Unique 子库，则需要配置 idfa 专用域名
    // [BDAutoTrack.sharedTrack setRequestIDFAHostBlock:^NSString * _Nullable(BDAutoTrackServiceVendor  _Nonnull vendor, BDAutoTrackRequestURLType requestURLType) {
    //     return @"https://gator-tracking.datafinder.volces.com";
    // }];

    // 授权后
    [[BDAutoTrack sharedTrack] startTrack]; //SDK启动

    return YES;
}

// 上报事件 以及 设置登录态
#import <RangersAppLog/RangersAppLog.h>

// ...

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // 上报事件
    [BDAutoTrack eventV3:@"event_test" params:@{@"key_string": @"value_string", @"key_int": @(10)}];

    // 设置登录态, 版本6.13.0+
    [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"当前登陆态UUID"];
}

@end

Swift请参考：

import RangersAppLog

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    /* 初始化SDK开始 */
    let config = BDAutoTrackConfig(appID: "{{APPID}}")
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = "App Store"
    // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址
    config.serviceVendor = .private
    BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in
        return "https://gator.volces.com"
    }

    config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭
    config.showDebugLog = false // true:开启日志，需要参考4.3设置Logger，false:关闭日志
    config.logNeedEncrypt = true // 加密开关，true开启，false关闭
    BDAutoTrack.sharedTrack(with: config)
    /* 初始化SDK结束 */

    // 若使用 Unique 子库，则需要配置 idfa 专用域名
    // BDAutoTrack.shared().setRequestIDFAHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in
    //     return "https://gator-tracking.datafinder.volces.com"
    // }

    BDAutoTrack.shared().start() //SDK启动

    return true
}

import RangersAppLog

// ...

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        // 上报事件
        BDAutoTrack.eventV3("event", params: ["key_string": "value_string", "key_int": 10])

        // 设置登录态, 版本6.13.0+
        BDAutoTrack.setCurrentUserUniqueID("{{USER_UNIQUE_ID}}")
    }
}

Objective-C请参考：

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

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    /* 初始化SDK开始 */
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = @"App Store";

    // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址，详情见上文 获取数据上送地址 章节
    config.serviceVendor = BDAutoTrackServiceVendorPrivate;
    BDAutoTrackRequestHostBlock block =
        ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
            return @"https://****.****.com";
        };
    [BDAutoTrack setRequestHostBlock:block];

    config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
    config.showDebugLog = NO; // YES:开启日志，NO:关闭日志
    config.logNeedEncrypt = YES; // 加密开关，YES开启，NO关闭
    [BDAutoTrack sharedTrackWithConfig:config];
    /* 初始化SDK结束 */

    // 授权后
    [[BDAutoTrack sharedTrack] startTrack]; //SDK启动

    return YES;
}

Swift请参考：

import RangersAppLog

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    /* 初始化SDK开始 */
    let config = BDAutoTrackConfig(appID: "{{APPID}}")
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = "App Store"
    // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址
    config.serviceVendor = .private
    BDAutoTrack.setRequestHostBlock {(vendor: BDAutoTrackServiceVendor, requestURLType:BDAutoTrackRequestURLType) -> String? in
        return "https://****.****.com"
    }

    config.autoTrackEnabled = true // 全埋点开关，true开启，false关闭
    config.showDebugLog = false // true:开启日志，需要参考4.3设置Logger，false:关闭日志
    config.logNeedEncrypt = true // 加密开关，true开启，false关闭
    BDAutoTrack.sharedTrack(with: config)
    /* 初始化SDK结束 */

    BDAutoTrack.shared().start() //SDK启动

    return true
}

• 云原生（华北：北京）：https://gator.volces.com
• 云原生（华南：广州）：https://gator.uba.cn-guangzhou.volces.com
• 云原生（海外：亚太东南-柔佛）：https://gator.uba.ap-southeast-1.volces.com

// ...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    /* 初始化SDK开始 */
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = @"App Store";

    // 设置数据上送地址，您需根据使用的DataFinder服务所在地域配置上送地址
    config.serviceVendor = BDAutoTrackServiceVendorPrivate;
    BDAutoTrackRequestHostBlock block =
        ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
            // 云原生-（华北：北京）
            return @"https://gator.volces.com";

            // 云原生-（华南：广州）
            // return @"https://gator.uba.cn-guangzhou.volces.com";
            // 云原生-（海外：亚太东南-柔佛）
            // return @"https://gator.uba.ap-southeast-1.volces.com";
        };
    [BDAutoTrack setRequestHostBlock:block];

    config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
    // ...

    return YES;
}

// ...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    /* 初始化SDK开始 */
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = @"App Store";

    // 设置私有化部署数据上送地址，替换{{REPORT_URL}} 例如 https://yourdomain.com，注意域名后不要加“/”
    config.serviceVendor = BDAutoTrackServiceVendorPrivate;
    BDAutoTrackRequestHostBlock block =
        ^NSString *(BDAutoTrackServiceVendor vendor, BDAutoTrackRequestURLType requestURLType) {
            return @"{{REPORT_URL}}";
        };
    [BDAutoTrack setRequestHostBlock:block];

    config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
    // ...

    return YES;
}

// ...
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    /* 初始化SDK开始 */
    BDAutoTrackConfig*config = [BDAutoTrackConfig configWithAppID:@"{{APPID}}" launchOptions:launchOptions];
    // 设置渠道，iOS一般默认App Store渠道
    config.channel = @"App Store";

    // 设置数据上送地址
    // 国内环境请配置为BDAutoTrackServiceVendorCN
    config.serviceVendor = BDAutoTrackServiceVendorCN;
    // 海外BytePlus环境请配置为BDAutoTrackServiceVendorSG
    // config.serviceVendor = BDAutoTrackServiceVendorSG;

    config.autoTrackEnabled = YES; // 全埋点开关，YES开启，NO关闭
    // ...

    return YES;
}

Objective-C请参考：

#import <RangersAppLog/RangersAppLog.h>

// ...

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // 上报事件
    [BDAutoTrack eventV3:@"event_test" params:@{@"key_string": @"value_string", @"key_int": @(10)}];
}

@end

Swift请参考：

import RangersAppLog

// ...

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        // 上报事件
        BDAutoTrack.eventV3("event", params: ["key_string": "value_string", "key_int": 10])
    }
}

Objective-C请参考：

#import <RangersAppLog/RangersAppLog.h>

// ...

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    // ...
    // 设置登录态, 版本6.13.0+
    [[BDAutoTrack sharedTrack] setCurrentUserUniqueID:@"当前登陆态UUID"];
}

@end

Swift请参考：

import RangersAppLog

// ...

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        // 设置登录态, 版本6.13.0+
        BDAutoTrack.setCurrentUserUniqueID("{{USER_UNIQUE_ID}}")
    }
}

全局API

sharedTrackWithConfig

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

sharedTrack

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

startTrack

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

trackWithConfig

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

setRequestHostBlock

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

setCurrentUserUniqueID

设置用户登录态。

clearUserUniqueID

退出用户登录态。

eventV3

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

setCustomHeaderValue

设置自定义的公共属性。

removeCustomHeaderValueForKey

移除自定义的公共属性。

configWithAppID

根据App ID获得一个config对象。

模块API

AB实验功能API说明

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

用户属性功能API说明

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

元素曝光功能API说明

本功能在6.10.0+后开始支持。当组件出现在屏幕可视范围内会自动触发一个曝光事件。