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

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": {
    "aid": "00000000",
    "channel": "yourChannel",
    "language": "zh-Hans",
    "region": "CN",
    "timezone": 8,
    "tz_name": "Asia/Shanghai",
    "tz_offset": 28800,
    "cdid": "93759594-3924-4a1f-aa2d-4172bee1af05",
    "aaid": "e9359704-e585-4411-88e4-9a02bc7d2c2e",
    "clientudid": "21cbd1c4-e035-47d4-b341-9e1f10af0549",
    "openudid": "3ef21af7-5032-4319-ae24-460c38dbad9c",
    "platform": "Android",
    "sdk_lib": "Android",
    "sdk_version": "1.3.1-all-rc1",
    "sdk_version_code": 10010301,
    "sdk_version_name": "1.3.1-all-rc1",
    "device_model": "emulator",
    "device_brand": "HUAWEI",
    "device_manufacturer": "HUAWEI",
    "device_type": "phone",
    "rom_version": "emulator 5.0.0.123(SP16DEVC00E123R4P11log)",
    "os": "Android",
    "os_api": 14,
    "os_version": "5.0.2",
    "cpu_abi": "arm64-v8a",
    "package": "com.bytedance.harmonydemo",
    "app_version": "1.0.0",
    "version_code": 1000000,
    "install_time": 1750988605542,
    "update_time": 1750990172484,
    "display_name": "label",
    "access": "wifi",
    "density_dpi": 520,
    "resolution": "1260 * 2720",
    "user_unique_id": "your_uuid",
    "bd_did": "7086404173897436672",
    "install_id": "7086404173898187009",
    "ssid": "1731359178819711838",
    "register_time": 1750990186975
  },
  "launch": [
    {
      "local_time_ms": 1750991430396,
      "tea_event_index": 5,
      "session_id": "0fa20a1a-5ff8-4b44-8853-963a70e73d89_0000000_2",
      "$resume_from_background": true,
      "$page_key": "pages/Index_1",
      "ssid": "1731359178819711838",
      "user_unique_id": "your_uuid",
      "datetime": "2025-06-27 10:30:30",
      "nt": 4
    }
  ],
  "terminate": [
    {
      "local_time_ms": 1750991429102,
      "tea_event_index": 4,
      "session_id": "0fa20a1a-5ff8-4b44-8853-963a70e73d89_0000000_1",
      "stop_timestamp": 1750991429.102,
      "duration": 55.793,
      "$page_key": "pages/Index_1",
      "ssid": "1731359178819711838",
      "user_unique_id": "your_uuid",
      "datetime": "2025-06-27 10:30:29",
      "nt": 4
    }
  ],
  "event_v3": [
    {
      "local_time_ms": 1750991378759,
      "tea_event_index": 2,
      "session_id": "0fa20a1a-5ff8-4b44-8853-963a70e73d89_0000000_1",
      "ssid": "1731359178819711838",
      "user_unique_id": "your_uuid",
      "datetime": "2025-06-27 10:29:38",
      "nt": 4,
      "params": {
        "key_string": "value_string",
        "key_int": 10,
        "$app_version": "1.0.0"
      },
      "event": "event_name"
    }
  ],
  "local_time": 1750991429.164
}

事件

存放事件及事件属性。
事件分为 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

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

无需配置，使用默认的数据上报地址

暂不支持

SaaS-云原生
私有化 492 版本

已支持

环境已完成适配，platform 以 openHarmony 上报。
如果是老的私有化版本升级上来的，需要联系火山引擎技术支持人员获取 HarmonyOS Next SDK 新版适配包。

SaaS-非云原生、
私有化 492 之前版本

不支持

环境不支持或未完成适配，如果想提早集成，SDK 的 platform 会以 Android 上报。

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

// 入口文件，比如 ets/entryability/EntryAbility.ets
import { AbilityConstant, UIAbility, Want, /***/ } from '@kit.AbilityKit'
// ...
import { AppLog, InitConfig, createByDomain } from '@volcengine/applog'

// 建议将实例挂载给一个独立模块，导入这个辅助模块，该文件建议放在 ets/Global.ets
import Global from '../Global'

class EntryAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
        // 创建新的 AppLog 实例
        let appLog = new AppLog()
        // 鸿蒙 sdk channel 作为可选参数
        let config = new InitConfig('yourAppId', 'yourChannel')
          // 是否打开日志
          .setLogEnabled(true)
          // 假如是上报到云原生，就可以设置上报地址为云原生域名
          .setUri(createByDomain('https://gator.volces.com'))
        // init sdk 传入配置，init 之后可以
        appLog.init(this.context, config)

        // 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求
        appLog.start()

        // 如果要方便在其他文件中使用实例，建议将实例挂载给一个独立模块
        Global.appLog = appLog
    }
    // ...
}
// ...

// 一个独立模块，方便全局导入使用，ets/Global.ets
import type { AppLog } from '@volcengine/applog'
class Global {
  static appLog: AppLog
}
export default Global

// 在组件中上报事件以及设置登录态，比如 ets/pages/Index.ets
import Global from '../Global'

@Entry
@Component
struct Index {
  // ...
  build() {
    Button('上报', { stateEffect: true })
      .onClick(() => {
        // 上报事件
        Global.appLog?.event('event_name', {
          'key_string': 'value_string',
          'key_int': 10
        })

        // 设置登录态
        Global.appLog?.user()?.setUserUniqueID('your_uuid');
      })
  }
}

// 创建新的 AppLog 实例
let appLog = new AppLog()
// 鸿蒙 sdk channel 作为可选参数
let config = new InitConfig('yourAppId', 'yourChannel')
  // 是否打开日志
  .setLogEnabled(true)
  // 假如是上报到云原生，就可以设置上报地址为云原生域名
  .setUri(createByDomain('https://gator.volces.com'))
// init sdk 传入配置，init 之后可以
appLog.init(this.context, config)

// 鸿蒙 SDK 需要手动调用 start 才开始采集敏感信息与发送请求
appLog.start()

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

// ...
let config = new InitConfig('yourAppId', 'yourChannel')
  // 是否打开日志
  .setLogEnabled(true)
  // 云原生-（华北：北京）
  .setUri(createByDomain('https://gator.volces.com'))
  // 云原生-（华南：广州）
  // .setUri(createByDomain('https://gator.uba.cn-guangzhou.volces.com'));
  // 云原生-（海外：亚太东南-柔佛）
  // .setUri(createByDomain('https://gator.uba.ap-southeast-1.volces.com'));
// init sdk 传入配置，init 之后可以
appLog.init(this.context, config)
// ...

// ...
let config = new InitConfig('yourAppId', 'yourChannel')
  // 是否打开日志
  .setLogEnabled(true)
  // 设置私有化部署数据上送地址，替换your_REPORT_URL 例如 https://yourdomain.com
  .setUri(createByDomain('your_REPORT_URL'))
// init sdk 传入配置，init 之后可以
appLog.init(this.context, config)
// ...

// ...
let config = new InitConfig('yourAppId', 'yourChannel')
  // 是否打开日志
  .setLogEnabled(true)
  // 无需调用setUri
// init sdk 传入配置，init 之后可以
appLog.init(this.context, config)
// ...

// 示例：上报事件 event_name，该事件包含两个属性
// 一个 string 类型的属性，属性名为 key_string，属性值为 value_string
// 一个 int 类型的属性，属性名为 key_int，属性值为 10
// 置于业务逻辑对应位置
appLog.event('event_name', {
  'key_string': 'value_string',
  'key_int': 10
})

// 设置 UUID
appLog.user()?.setUserUniqueID('your_uuid')

全局API

init

对SDK实例进行初始化设置，依赖ability的context，因此调用时机适合在onCreate生命周期里。

start

让SDK实例开始真正准备执行事件上报，调用时机在init之后。

event

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

setHeaderInfo

设置自定义的公共属性。

removeHeaderInfo

移除自定义的公共属性。

topicReceiver

SDK内部实现了一套订阅发布机制，如果希望订阅SDK内部一些特定的事件，需要先调用topicReceiver获得实例的TopicReceiver对象。

模块API

InitConfig API说明

用来专门管理SDK初始化配置的类，提供一系列方法来设置初始化配置项。

User插件API说明

用户信息插件，设置与获取用户信息，如 user_unique_id。

AB实验功能插件API说明

SDK提供AB实验能力，提供了AB实验插件，该插件包含一系列的方法：getAbConfig、getAbSdkVersion、getAllAbTestConfigs。

用户属性功能插件API说明

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

组件曝光功能插件API说明

提供设置组件曝光采集能力，提供了一些方法：observeByNodeId、disposeByNodeId。