Web/JS SDK 埋点与属性

上报事件和属性前，请先阅读数据格式介绍。

1.1 登录态变化调用

1.1.1 账户登录

如您的产品中有账户体系，请在用户登录后立即设置uuid，以保证用户登录前后口径一致性。

window.collectEvent('config', {
    user_unique_id: "{{USER_UNIQUE_ID}}"  
});

1.1.2 账户登出

在账户登出时调用。

window.collectEvent('config', {
    user_unique_id: null 
});

1.2 设置用户属性

1.2.1 profileSet

设置用户属性，存在则覆盖，不存在则创建。

// 示例：设置用户属性，属性名为key，属性值为value
window.collectEvent('profileSet', {
    key: 'value' // 值支持字符串，数字，数组
})

1.2.2 profileSetOnce

设置用户属性，存在则不设置，不存在则创建，适合首次相关的用户属性，比如首次访问时间等。

// 示例：设置用户属性，属性名为key_once，属性值为value_once
window.collectEvent('profileSetOnce', {
    key_once: 'value_once' // 值支持字符串，数字，数组
})

1.2.3 profileIncrement

设置数值类型的属性，可进行累加。

// 示例：设置用户属性，属性名为key，属性值为1
window.collectEvent('profileIncrement', {
    key: 1
})

1.2.4 profileAppend

设置List类型的用户属性，可持续向List内添加。

// 示例：设置用户属性，属性名为key，原本已有属性值，现添加属性值为value_append
window.collectEvent('profileAppend', {
    key: 'value_append'
})

1.2.5 profileUnset

删除用户的属性。

// 示例：删除用户属性，属性名为key
window.collectEvent('profileUnset', 'key')

1.3 匿名ID

匿名用户ID，用于代替webid的功能。开启匿名用户ID的设置后，不再请求和上报webid，统一由匿名ID代替。

1.3.1 开启匿名ID

// 示例
window.collectEvent('init', {
   enable_anonymousid: true
})

1.3.2 设置匿名ID

// 示例
window.collectEvent('setAnonymousId', 'xxxx')

2.1 上报代码埋点

用户行为日志采用事件event+属性params的形式，事件一般对应多个属性，也可以仅有事件没有属性。代码埋点方案一般由数据分析师或产品运营设计。

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

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

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

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

2.2 事件公共属性

如需在每个事件中都包括某属性，可通过公共属性设置，无需在每个事件中重复设置。公共属性只需设置一次，即可包括在所有代码埋点事件、预置事件和全埋点事件中。当页面发生跳转后，需要重新加载SDK和重新设置需要的公共属性（单页应用除外）

2.2.1 设置公共属性

// 示例：设置自定义的公共属性，属性名为key_public，属性值为value_public
window.collectEvent('config', {
   key_public: 'value_public'
});

2.3 页面跳转前上报埋点

请注意，在埋点设计时，不建议在发送事件后紧接着进行页面跳转。这种情况下，上报请求可能会失败，统计数据可能缺失。请考虑以下两种方式之一：

1. 使用beconEvent。
   beconEvent会将埋点通过浏览器的特性sendbeacon来发送，尽可能补偿数据上报。

   window.collectEvent('beconEvent', 'event', {})
   window.location.href = 'https://xxx.com';
   

2. 添加延时，给ajax一些时间。

   window.collectEvent('test_event');
   setTimeout(()=>{
       window.location.href = 'https://xxx.com'
   }, 150)
   

3.1 config(paramsObj)

config 命令用于设置上报自定义字段和一些配置项。

• 需在 init 之后调用。

• 可多次调用，新的配置会和旧的配置合并，同名的设置会被覆盖（等同 Object.assign）。

• 参数为一个对象。
  参数分类：

  • SDK自身配置项及调试相关字段

  • 用户标识相关字段

  • 用户属性（公共属性）

    • 预设

    • 自定义

  • 事件共有的事件属性

// 1. 第1次调用

window.collectEvent('config', {
    language: 'cn',
    weeks: 'Monday',
})
window.collectEvent('send')
// 2. 此时发送的事件都包含 cn ， Monday

// 3. 第2次调用

window.collectEvent('config', {
    language: 'en',
})
// 4. 此时发送的事件都包含 en ， Monday

config中包含预设字段，例如用户标识、用户属性、公共属性、系统占用等。以下字段为被SDK占用的字段，每个字段有特定的含义，可设置字段的优先级高于SDK默认的赋值。

3.2 页面浏览事件

3.2.1 SDK 默认调用

predefine_pageview事件默认调用，如需关闭，请参考Web/JS SDK 集成 3.3节。

3.2.2 业务手动调用

调用该方法以主动上报一次 pv 事件，参数类型同普通事件的事件属性。
如果传入了自定义的事件属性，会和预设的事件属性进行合并；如果有同名属性，则会覆盖掉预设属性。

window.collectEvent("predefinePageView")
window.collectEvent("predefinePageView", {/**...*/})
// 覆盖默认的属性

window.collectEvent("predefinePageView", {
    url: 'xxx',
    url_path: 'xxx'
    // ...
})

3.3.3 事件预置属性

3.3.4 对SPA的支持

因为默认情况下，SDK只会在页面加载后，并初始化完成后上报一次 pv 事件，但SPA页面会存在多个页面路由，SDK只会在主页面加载一次，所以在切换页面的时候不会再发起pv，造成后续的页面没有pv数据。因此可以开启SPA参数，SDK会在路由变化时重新上报PV：

window.collectEvent("init", {
    spa: true
})

当然，可能会存在SDK监听到路由变化时，一些页面参数并不是最新的，您也可以手动在路由变化时去上报PV。以react示例：

// <Router history={history} onUpdate={onUpdate}>

function onUpdate() {
    window.collectEvent("predefinePageView")
}

3.3 获取平台生成的各种ID

获取SDK的token信息，里面包含web_id、ssid、user_unique_id信息。 如果您需要获取SDK的ID信息，进行其他设置的话，可以如下：

window.collectEvent('getToken', (token) => {
    //token数据内容类似如下：
    {
        "web_id":"6748002161499735560",
        "ssid":"579bc89a-bd45-4021-8314-669c35f38e3d",
        "user_unique_id":"xxx",
    }
    window.collectEvent('test', {
      id: web_id/ssid
    })
});

3.4 自定义webid

如需更改SDK默认的webid，请在SDK初始化的时候设置enable_custom_webid: true，然后通过setWebIDviaUnionID或者setWebIDviaOpenID设置，示例如下：

window.collectEvent('init', {
    enable_custom_webid: true
});
window.collectEvent('setWebIDviaUnionID', 'ssss')
window.collectEvent('setWebIDviaOpenID', 'ssss')

需要注意的是，当设置了enableCustomWebid，必须调用setWebIDviaUnionID或者setWebIDviaOpenID其中的一个设置了webid后，SDK才会继续执行后续的流程。
这种场景适合H5页面在微信小程序中打开，需要传递微信的unionID或者openID给H5页面。