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

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
• 需在小游戏中添加白名单：https://gator.uba.ap-southeast-1.volces.com

• channel: 'cn'
• 需在小游戏中添加白名单：https://mcs.volceapplog.com

• channel: 'sg'
• 需在小游戏中添加白名单：https://mcs.tobsnssdk.com

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

• https://tab.volces.com
• 需在小游戏中添加对应地址至小游戏的白名单中

• https://tab.ab.ap-southeast-1.volces.com
• 需在小游戏中添加对应地址至小游戏的白名单中

无需手动配置

无需手动配置

npm install @datarangers/sdk-qg

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

// 入口文件 game.js
import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';

$$sdk.init({ //调用init接口初始化SDK，配置初始化参数
    // 请更换成自己的app_id
    app_id: 0,
    // channel_domain用于设置数据上报域名，SaaS-云原生环境和私有化环境需设置，示例设置结果假设是SaaS-云原生华北地域环境
    channel_domain: 'https://...',
    log: true,
});
$$sdk.send(); //当init初始化调用之后，需要调用send方法，SDK才开始上报事件。

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

new Main();

// main.js
import $$sdk from '@datarangers/sdk-qg';

export default class Main {
    constructor() {
        // ...
    }

    start() {
        // ...
        // 调用event接口上报自定义事件和事件属性
        $$sdk.event('test', {
            abc: 123,
        });
    }
}

import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';

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

new Main();

1. 在主入口文件（demo中的game.js文件）中初始化，操作与上述步骤类似

   import Main from './js/main';
   import $$sdk from '@datarangers/sdk-qg';
   
   $$sdk.init({
       // 请更换成自己的app_id
       app_id: 0,
       log: true,
   });
   $$sdk.send();
   
   new Main();
   

2. 在另外的文件中，比如main.js

   import $$sdk from '@datarangers/sdk-qg';
   
   export default class Main {
       constructor() {
           // ...
       }
   
       start() {
           // ...
           // 调用event接口上报自定义事件和事件属性
           $$sdk.event('test', {
               abc: 123,
           });
       }
   }
   

import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';

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

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

new Main();

import Main from './js/main';
import $$sdk from '@datarangers/sdk-qg';

$$sdk.init({
    // 请更换成自己的app_id
    app_id: 0,
    // 假设是云原生环境
    channel_domain: 'https://gator.volces.com',
    log: true,
});
$$sdk.send();

new Main();

核心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。