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

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

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

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

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

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

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

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

埋点、全埋点

user

存放用户属性数据，比如web_id、user_unique_id这些重要属性。

[
  {
    events: [
      {
        event: 'predefine_pageview',
        params: '{"scene":1001,……}',
        local_time_ms: 1745897787756,
        session_id: 'd8b28410-6079-42da-9f91-5a49d6ffb01f',
      },
    ],
    user: {
      web_id: '7498573*****',
      user_unique_id: 'zhangsan',
    },
    header: {
      app_id: 0,
      app_version: '',
      os_name: 'mac',
      os_version: '11_2_0',
      // ……
      custom: {
        custom_platform: 'miniProduct',
        // ……
      },
      // ……,
    },
  },
]

header

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

events

存放事件及事件属性。
本身是一个数组，支持携带多个事件。
每个事件都有event、params、local_time_ms、session_id几个字段，其中local_time_ms、session_id是SDK自动产生的，而event、params是业务设置的，event是事件名，params存放的是事件属性（值是JSON对象进行了序列化操作）。

数据上报地址
（channel_domain）

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

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

• channel: 'cn'

• channel: 'sg'

分流地址
（ab_channel_domain，仅开启A/B实验时需配置）

• https://tab.volces.com

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

无需手动配置

无需手动配置

npm install @datarangers/sdk-electron

以下为一个简单的集成SDK代码示例，您可通过此示例来快速了解SDK集成时的代码结构、涉及的核心接口、典型的配置参数等，后续步骤中会为您逐步介绍SDK集成的详细操作要点。
引入SDK后，传入相关初始化参数，获得SDK实例，大多数api都是挂载在SDK的实例上的。需要注意的是，SDK的初始化必须要在Electron的主进程中。

// SDK需要在Electron主进程初始化
const { SDK } = require('@datarangers/sdk-electron');

const $$sdk = new SDK({
    app_id: 0000,                        //  替换成自己的app_id
    channel: 'cn',                       //  'sg' 新加坡 'va' 美东
    log_level: 'info',                    //  启用日志输出(可选)
    channel_domain: '',                  //  私有化上报的地址 (https?//\w+)
    // enable_ab_test: false,               //  是否开启AB实验，并使用AB实验相关API
    // ab_channel_domain: 'https://'        //  ab实验域名,当开启AB实验时需要设置该域名
});

通过SDK上报事件

// 参数1是字符串，是事件名
// 参数2是个对象，是事件属性
$$sdk.event('event_name', {
    paramA: 'xxx',
    paramB: 'yyy',
});

在渲染进程中使用SDK可以通过如下方式

// 渲染进程可通过如下方式使用SDK上报
// 主进程
ipcMain.handle('sdk-event', (e, eventInfo) => {
  $$sdk.event(eventInfo.name, eventInfo.params);
});

// 渲染进程
ipcRenderer.invoke('sdk-event', {
  name: 'event-name',
  params: {
    eventField: '',
  },
});

// SDK需要在Electron主进程初始化
const { SDK } = require('@datarangers/sdk-electron');

const $$sdk = new SDK({
    app_id: 0000,                        //  替换成自己的app_id
    channel: 'cn',                       //  'sg' 新加坡 'va' 美东
    log_level: 'info',                   //  启用日志输出(可选)
    channel_domain: '',                  //  私有化上报的地址 (https?//\w+)
});

1. 在主进程中上报事件

   $$sdk.event('event_name', {
       paramA: 'xxx',
       paramB: 'yyy',
   });
   

2. 在渲染进程中上报事件

   • 首先在主进程中准备接收事件的IPC通道，并监听事件上报

   ipcMain.handle('sdk-event', (e, eventInfo) => {
     $$sdk.event(eventInfo.name, eventInfo.params);
   });
   

   • 然后再渲染进程中发送事件

   ipcRenderer.invoke('sdk-event', {
     name: 'event-name',
     params: {
       eventField: '',
     },
   });
   

$$sdk.config({
    user_unique_id: '{{你的用户唯一值}}'
});

const $$sdk = new SDK({
    // ...
    channel_domain: '{{你对应的上报域名}}',
});

核心API

初始化

对SDK实例进行初始化配置。

config

调用config对事件进行一些设置，比如设置公共属性、设置user_unique_id等。可以调用多次，后面设置会覆盖之前相同设置项。

event

使用event方法可以上报自定义事件。

模块API

AB实验模块及API

此模块提供AB实验能力，并提供了一系列的方法：getVar、getAllVars、getAbSdkVersion。

用户属性模块及API

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