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

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

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

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

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

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

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

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

埋点、全埋点

header

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

{
  "magic_tag":"ss_app_log",
  "header":{
    "platform":"Android",
    "sdk_lib":"Android",
    "device_model":"M2012K11AC",
    "device_brand":"Redmi",
    "device_manufacturer":"Xiaomi",
    "cpu_abi":"arm64-v8a",
    "sdk_target_version":29,
    "os":"Android",
    "os_api":33,
    "os_version":"13",
    "sdk_version":61710190,
    "sdk_version_code":16169789,
    "sdk_version_name":"6.17.1",
    "channel":"test",
    "not_request_sender":0,
    "aid":*******,
    "app_region":"CN",
    "user_unique_id":"test_unique_id",
    "density_dpi":440,
    "display_density":"xxhdpi",
    "resolution":"2400x1080",
    "language":"zh",
    "timezone":8,
    "region":"CN",
    "tz_name":"Asia\/Shanghai",
    "tz_offset":28800,
    "access":"wifi",
    "package":"com.bytedance.test",
    "app_version":"2.3",
    "version_code":11,
    "update_version_code":11,
    "manifest_version_code":11,
    "display_name":"AppLog",
    "rom":"MIUI-V816.0.6.0.TKHCNXM",
    "rom_version":"miui_V816_V816.0.6.0.TKHCNXM",
    "bd_did":*******,
    "install_id":*******,
    "register_time":1744808564902,
    "sig_hash":*******,
    "sim_region":"gb",
    "carrier":"中国移动",
    "mcc_mnc":"46000",
    "clientudid":"ca9cc331-7103-4731-b737-048fbd1c03f2",
    "openudid":*******,
    "cdid":"64234011-3fd2-49f4-ba3e-c7e80cf67070",
    "oaid":*******,
    "ssid":*******
  },
  "launch":[
    {
      "local_time_ms":1744808577740,
      "tea_event_index":1001,
      "session_id":"0ce8d2ed-f4c4-4d71-9d2a-f322f6ce6137",
      "user_unique_id":"test_unique_id",
      "ssid":*******,
      "datetime":"2025-04-16 21:02:57",
      "ab_sdk_version":"348170",
      "$page_title":"初始化页面",
      "$page_key":"com.bytedance.test.InitActivity",
      "$resume_from_background":"false"
    },
  ],
  "terminate":[
    {
      "local_time_ms":1744808575991,
      "tea_event_index":1003,
      "session_id":"1fd1f14a-e32e-47e0-922e-73672aa55de6",
      "stop_timestamp":1744808575,
      "duration":8,
      "datetime":"2025-04-16 21:02:55",
      "user_unique_id":"test_unique_id",
      "ssid":*******,
      "ab_sdk_version":"348170",
      "launch_from":1,
      "$page_title":"初始化页面",
      "$page_key":"com.bytedance.test.InitActivity",
      "activites":[
        [
          "com.bytedance.test.InitActivity",
          4
        ]
    }
  ],
  "event_v3":[
    {
      "local_time_ms":1744808577743,
      "tea_event_index":1002,
      "session_id":"02cd457b-c9bf-4252-8bd2-a940426f18cb",
      "user_unique_id":"test_unique_id",
      "ssid":*******,
      "event":"abtest_exposure",
      "params":{
        "ab_sdk_version":*******,
        "$app_version":"2.3"
      },
      "nt":4,
      "datetime":"2025-04-16 21:02:57",
      "ab_sdk_version":*******
    }
  ],
  "local_time":1744808577
}

事件

存放事件及事件属性。
事件分为 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 对象进行了序列化操作）。

数据上报地址

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

https://gator.uba.cn-guangzhou.volces.com

• 需要配合使用 cn 包：'com.bytedance.applog:RangersAppLog-xxx-cn:version'

• https://gator.uba.ap-southeast-1.volces.com
• 需要配合使用海外包：'com.bytedance.applog:RangersAppLog-xxx-global:version'

• 无需配置，使用默认的数据上报地址
• 需要配合使用 cn 包：'com.bytedance.applog:RangersAppLog-xxx-cn:version'

• 无需配置，默认上报到 SG
• 需要配合使用海外包：'com.bytedance.applog:RangersAppLog-xxx-global:version'

分流地址

• https://tab.volces.com

• https://tab.ab.ap-southeast-1.volces.com

无需手动配置

无需手动配置

1. 添加火山仓库依赖

   • Gradle 7.0 以下：在根目录级别的 build.gradle 中添加 maven 仓库

     // 在根目录级别的 build.gradle 中添加 maven 仓库
     allprojects {
         repositories {
             // 其他仓库
             // 配置 Finder SDK 拉取仓库
             maven {
                 url 'https://artifact.bytedance.com/repository/Volcengine/'
             }
         }
     }
     

   • Gradle 7.0 以上：在根目录级别的 setting.gradle 中添加 maven 仓库

     // 在根目录级别的 setting.gradle 中添加 maven 仓库
     dependencyResolutionManagement {
         repositories {
             // 其他仓库
             // 配置 Finder SDK 拉取仓库
             maven {
                 url = uri("https://artifact.bytedance.com/repository/Volcengine/")
             }
         }
     }
     

2. 添加 SDK 依赖：在 App 级别下 build.gradle 文件的 dependencies 中 引入 SDK。

   // 在 App 级别下 build.gradle 文件的 dependencies 中 引入 SDK，集成 All 版本，推荐此版本
   implementation 'com.bytedance.applog:RangersAppLog-All-cn:6.17.4'
   
   // 如您不需要全埋点采集、圈选、web 打通等功能，仅需要自定义埋点，可集成 Lite 版本：
   // 在 App 级别下 build.gradle 文件的 dependencies 中引入SDK，集成Lite版本
   implementation 'com.bytedance.applog:RangersAppLog-Lite-cn:6.17.4'
   

示例视频为 Gradle 7.0 以上

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

// 第一个参数 APPID: 参考 准备工作-步骤2 获取
// 第二个参数 CHANNEL: 填写渠道信息（您的包当前是上传到哪个渠道，比如小米、华为、Google），请注意不能为空
// yourAPPID、yourCHANNEL 为占位符，请替换为实际内容
final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
// 设置数据上送地址，您需根据使用的 DataFinder 服务所在地域配置上送地址，
// 此处以SaaS-云原生的华北地域做示例，详情见上文 获取数据上送地址 部分
config.setUriConfig(UriConfig.createByDomain("https://gator.volces.com", null));
// 确保 start 才开始用用户信息采集
config.setAutoStart(false);
// 全埋点开关，true开启，false关闭
config.setAutoTrackEnabled(true);
// true:开启日志，false:关闭日志，默认关闭，可在本地调试时打开
config.setLogEnable(false);
// 加密开关，true:开启，false:关闭
AppLog.setEncryptAndCompress(true);
// 初始化一次即可
// Applition 中初始化建议使用该方法
AppLog.init(this, config);
// Activity 中初始化建议使用该方法
AppLog.init(this, config, this);

// 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
AppLog.start();

• 仅上报事件的代码埋点，示例如下：

// 示例：上报事件 event，该事件不包含属性
// 置于业务逻辑对应位置
AppLog.onEventV3("event");

• 上报事件和对应属性的代码埋点，示例如下：

// 示例：上报事件 event，该事件包含两个属性
// 一个 string 类型的属性，属性名为 key_string，属性值为 value_string
// 一个 int 类型的属性，属性名为 key_int，属性值为 10
// 置于业务逻辑对应位置
JSONObject paramsObj = new JSONObject();
try {
    paramsObj.put("key_string", "value_string");
    paramsObj.put("key_int", 10);
} catch (JSONException e) {
    e.printStackTrace();
}
AppLog.onEventV3("event", paramsObj);

不带自定义属性：

带自定义属性：

• 用户登录
  如您的产品中有账户体系，请在用户登录后立即设置 uuid，以保证用户登录前后口径一致性。 6.13.0+ 版本支持在初始化 AppLog 之前调用，用于设置已登录的用户 uuid。

  // 设置您账号体系的 ID, 并保证其唯一性
  // 6.13.0+ 版本支持此方法在初始化 AppLog 前调用
  AppLog.setUserUniqueID("your_USER_UNIQUE_ID");
  

  （6.13.0+ 版本不推荐使用）通过该方法设置 uuid，仅在首次冷启动时设置生效。由于 AppLog.setUserUniqueID 在 6.13.0+ 已支持在初始化之前调用，所以不再推荐使用该方法设置 uuid，建议统一使用 AppLog.setUserUniqueID。

  // 初始化时设置uuid
  // 6.13.0+版本请勿使用此方法
  config.setUserUniqueId("your_USER_UNIQUE_ID");
  

• 用户登出
  在账户登出时调用。

  // 登出时设置 uuid 为 null
  AppLog.setUserUniqueID(null);
  

用户登录：

用户登出

// 第一个参数 APPID: 参考 准备工作-步骤2 获取
// 第二个参数 CHANNEL: 填写渠道信息（您的包当前是上传到哪个渠道，比如小米、华为、Google），请注意不能为空
// yourAPPID、yourCHANNEL 为占位符，请替换为实际内容
final InitConfig config = new InitConfig("yourAPPID", "yourCHANNEL");
// 设置数据上送地址，您需根据使用的 DataFinder 服务所在地域配置上送地址，
// 此处以火山云做示例，详情见上文 获取数据上送地址 部分
config.setUriConfig(UriConfig.createByDomain("https://gator.volces.com", null));
// 确保 start 才开始用用户信息采集
config.setAutoStart(false);
// 全埋点开关，true开启，false关闭
config.setAutoTrackEnabled(true);
// true:开启日志，false:关闭日志，默认关闭，可在本地调试时打开
config.setLogEnable(false);
// 加密开关，true:开启，false:关闭
AppLog.setEncryptAndCompress(true);
// 初始化一次即可
// Applition 中初始化建议使用该方法
AppLog.init(this, config);
// Activity 中初始化建议使用该方法
AppLog.init(this, config, this);

// 请在用户授权后调用如下方法，start 开始实际采集用户信息+上报：
AppLog.start();

主要API

init

是对SDK实例进行初始化配置，init 之后产生的事件就都会存储到本地数据库里确保事件不会丢失。

start

启动 SDK，配合 initConfig.setAutoStart 使用，常用于隐私合规。

onEventV3

上报自定义事件，Android 支持 init 前 / init 后调用。

setUserUniqueID

设置 user_unique_id，可以调用多次，后面设置会覆盖之前相同设置项。

setHeaderInfo

设置事件公共属性，可以调用多次，后面设置会覆盖之前相同设置项。

removeHeaderInfo

移除事件公共属性。

setEncryptAndCompress

设置请求是否压缩加密，默认开启。

getDid

获取当前设备的 device_id。

getSsid

获取当前用户对应的 SSID。

addDataObserver / removeDataObserver

添加 / 移除各类数据回调监听，配套使用。

setGPSLocation

为事件追加 gps 相关自定义属性。

InitConfig API

InitConfig SDK 配置 API 介绍

InitConfig的一系列配置方法。

模块API

AB实验功能及 API 介绍

SDK 提供 AB 实验能力，并提供了一系列的方法：getAbConfig、getAbSdkVersion、getAllAbTestConfigs、setExternalAbVersion、pullAbTestConfigs。

用户属性模块及 API 介绍

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

元素曝光功能及 API 介绍

提供设置曝光采集的能力。