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

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

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

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

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

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

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

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

埋点、全埋点

user

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

[
  {
    events: [
      {
        event: 'app_launch',
        params: '{"path":"pages/index/index",……}',
        local_time_ms: 1745897787714,
        session_id: 'd8b28410-6079-42da-***',
      },
      {
        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: 'devtools',
      os_version: 'iOS 10.0.1',
      // ……
      custom: {
        custom_platform: 'miniProduct',
        mp_platform: '0',
        mp_platform_app_version: '8.0.5',
        // ……
      },
      // ……,
    },
  },
]

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-quick

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

// 入口文件app.ux
<script>
/**
 * 应用级别的配置，供所有页面公用
 */
import $$sdk from '@datarangers/sdk-quick';

// ...

export default {
  plugins: [
    $$sdk,
  ],
  onCreate() {
    $$sdk.init({//调用init接口初始化SDK，配置初始化参数
        // 请更换成自己的app_id
        app_id: 0,
        // channel_domain用于设置数据上报域名，SaaS-云原生环境和私有化环境需设置，示例设置结果假设是SaaS-云原生华北地域环境
        channel_domain: 'https://...',
        log: true,
    });
    $$sdk.send();
  }
}
</script>

// pages/Demo/index.ux
<template>
  <!-- template -->
</template>


<script>
import router from '@system.router'

export default {
  onInit() {
    // ...
    this.$app.$def.$$sdk.event('test', {
      abc: 123,
    });
  },
}
</script>

<script>
/**
 * 应用级别的配置，供所有页面公用
 */
import $$sdk from '@datarangers/sdk-quick';

// ...

export default {
  plugins: [
    $$sdk,
  ],
  onCreate() {
    $$sdk.init({
      // 请更换成自己的app_id
      app_id: 0,
      log: true,
    });
    $$sdk.send();
  }
}
</script>

1. 在主入口文件（demo中的app.ux文件）中初始化，操作与上述步骤类似，并且将$$sdk挂载到全局对象上

   <script>
   /**
    * 应用级别的配置，供所有页面公用
    */
   import $$sdk from '@datarangers/sdk-quick';
   
   // ...
   
   export default {
     plugins: [
       $$sdk,
     ],
     $$sdk,
     onCreate() {
       $$sdk.init({
         // 请更换成自己的app_id
         app_id: 0,
         log: true,
       });
       $$sdk.send();
     }
   }
   </script>
   

2. 在另外的文件中，比如pages/Demo/index.ux

   <template>
     <!-- template -->
   </template>
   
   
   <script>
   import router from '@system.router'
   
   export default {
     onInit() {
       // ...
       this.$app.$def.$$sdk.event('test', {
         abc: 123,
       });
     },
   }
   </script>
   

<script>
/**
 * 应用级别的配置，供所有页面公用
 */
import $$sdk from '@datarangers/sdk-quick';

// ...

export default {
  plugins: [
    $$sdk,
  ],
  $$sdk,
  onCreate() {
    $$sdk.init({
      // 请更换成自己的app_id
      app_id: 0,
      log: true,
    });
    $$sdk.send();

    // 使用setTimeout模拟异步设置，真实情况由业务自己决定
    setTimeout(() => {
      // 调用config接口设置自定义用户，假设设置的值是zhangsan，真实场景这个值一般是从业务的服务接口获取到的
      $$sdk.config({
        user_unique_id: 'zhangsan',
      });
      $$sdk.event('test_2', {
        hahah: 123,
      });
    }, 1000);
  }
}
</script>

<script>
/**
 * 应用级别的配置，供所有页面公用
 */
import $$sdk from '@datarangers/sdk-quick';

// ...

export default {
  plugins: [
    $$sdk,
  ],
  $$sdk,
  onCreate() {
    $$sdk.init({
      // 请更换成自己的app_id
      app_id: 0,
      // 假设是云原生环境
      channel_domain: 'https://gator.volces.com',
    });
    $$sdk.send();
  }
}
</script>

核心API

init

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

send

当init初始化调用之后，需要调用send方法，SDK才开始上报事件。在调用send方法之前，不会有事件上报。

config

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

event

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

模块API

AB实验模块及API

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

用户属性模块及API

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