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

1.1 登录态变化调用

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

$$Rangers.config({
    user_unique_id: '{{USER_UNIQUE_ID}}'
});

1.1.1 setUserUniqueID

2.6.0+版本，可以使用setUserUniqueID方法进行设置uuid

// 设置uuid
$$Rangers.setUserUniqueID('{{USER_UNIQUE_ID}}');

// 清空uuid
$$Rangers.setUserUniqueID(null);

1.2 设置用户属性

1.2.1 profileSet

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

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

1.2.2 profileSetOnce

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

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

1.2.3 profileIncrement

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

// 示例：设置用户属性，属性名为key，属性值为1
$$Rangers.profileIncrement({
    key: 1
});

1.2.4 profileAppend

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

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

1.2.5 profileUnset

删除用户的属性。

// 示例：删除用户属性，属性名为key
$$Rangers.profileUnset('key');

2.1 上报代码埋点

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

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

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

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

2.2 事件公共属性

如需在每个事件中都包括某属性，可通过公共属性设置，无需在每个事件中重复设置。公共属性只需设置一次，即可包括在所有代码埋点事件、预置事件和全埋点事件中。

2.2.1 设置公共属性

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

2.2.1.1 setHeaderInfo

2.6.0+版本，可以使用setHeaderInfo方法进行设置公共属性

// 示例：设置自定义的公共属性，属性名为key_public，属性值为value_public
$$Rangers.setHeaderInfo('key_public', 'value_public');

2.2.1.2 removeHeaderInfo

2.6.0+版本，可以使用removeHeaderInfo方法进行移除公共属性

// 示例：移除自定义的公共属性，属性名为key_public
$$Rangers.removeHeaderInfo('key_public');

3.1 SDK预设公共属性字段

SDK 会在 config({}) 中默认给一些字段赋值，这些SDK 默认设置的字段可以被覆盖。 请注意，增长分析产品中“分享用户”功能的昵称、头像、地域信息需您主动上报。

3.2 获取平台生成的各种ID

获取SDK的token信息，里面包含web_id、ssid、user_unique_id信息。

App({
  onLaunch: function () {
    this.$$Rangers = $$Rangers; // 绑定到全局的app，以便其他页面调用。
    this.$$Rangers.getToken((token) => { 
        // token数据内容例如：
        // {
        //    "web_id":"6748002161499735560",
        //    "ssid":"579bc89a-bd45-4021-8314-669c35f38e3d",
        //    "user_unique_id":"xxx",
        // }
    })
    // ...
  }
});

3.3 自定义webid 以及 与小程序内H5页面打通

3.3.1 自定义webid

如需更改SDK默认的webid，首先初始化时开启enable_custom_webid: true，然后再通过config设置web_id。

$$Rangers.init({
    // 其他初始化配置
    enable_custom_webid: true, // 初始化时开启enable_custom_webid
});

开启后，可在其他时机config设置web_id。

$$Rangers.config({
    web_id: '11111111111111', // webid的值要求纯数字或全是数字的字符串类型
});

也可以使用SDK提供的setWebIDviaUnionID和setWebIDviaOpenID两个方法来设置web_id

• setWebIDviaUnionID将小程序用户的unionid设置为web_id

$$Rangers.setWebIDviaUnionID('{{小程序用户的unionid}}');

• setWebIDviaOpenID将小程序用户的openid设置为web_id

$$Rangers.setWebIDviaOpenID('{{小程序用户的openid}}');

需要注意的是，当开启了自定义webid后，必须主动设置webid，SDK才会真正初始化并继续执行后续的流程。此场景适合H5页面在微信小程序中打开，需要传递微信的unionID或者openID给H5页面。

3.3.2 与小程序内H5页面打通

使用SDK提供的createWebViewUrl和createWebViewUrlAsync两个方法把web_id传递给H5页面，达到打通目的

• createWebViewUrl，在小程序内的webview组件的url上添加web_id传递给h5页面，需要注意的是该方法只能在SDK初始化完成后使用才能保证一定有web_id

// webview.wxml
<web-view src="{{ webUrl }}"></web-view>

// webview.js
Page({
   data: {
      webUrl: ''
   },
   onLoad(options) {
      let url = 'https://example/demo.html';
      this.setData({
         webUrl: $$Rangers.createWebViewUrl(url),
      });
   }
});

• createWebViewUrlAsync，这个是createWebViewUrl的异步版本，返回promise，不受SDK初始化情况的影响，一定会获取到web_id

// webview.wxml
<web-view src="{{ webUrl }}"></web-view>

// webview.js
Page({
   data: {
      webUrl: ''
   },
   onLoad(options) {
      let url = 'https://example/demo.html';
      $$Rangers.createWebViewUrlAsync(url).then((webviewUrl) => {
         this.setData({
            webUrl: webviewUrl,
         });
      });
   }
});

3.4 预置事件自动上报

使用预置事件自动上报，需要在初始化时配置auto_report参数为true。建议您开启此事件。 请注意：自定义事件的事件名请勿与预置事件重名。 小程序预置事件请参考：小程序预置事件及属性。

3.4.1 开启说明

通过init方法设置auto_report参数来开启功能

3.4.2 接入代码示例

• 不上报点击事件，但上报其他预定义事件，设置为true或者空对象{}就可以

const $$Rangers = require('@datarangers/sdk-mp'); 
$$Rangers.init({
    // ... 其他初始化配置
    // 或者 auto_report: {}
    auto_report: true
}); 
$$Rangers.send();

• 上报所有预定义事件，包括点击事件，需要将click设为true

const $$Rangers = require('@datarangers/sdk-mp'); 
$$Rangers.init({
    // ... 其他初始化配置
    auto_report: {
        click: true
    }
}); 
$$Rangers.send();

• 上报大部分预定义事件，但不上报error事件，将appError设为false，其他事件也类似设置

const $$Rangers = require('@datarangers/sdk-mp'); 
$$Rangers.init({
    // ... 其他初始化配置
    auto_report: {
        click: true,
        appError: false
    }
}); 
$$Rangers.send();

3.4.3 关于点击事件

当click设为true时，SDK将在那些绑定了一些事件函数的组件被点击时上报bav2b_click事件（目前只支持bindtap类型），该事件会采集组件上的dataset数据集中的内容作为参数上报。 假设如下组件，设置了id="diandian"以及data-hi="hello"

<view id="diandian" data-hi="hello" bindtap="tapMethod">点我</view>

当该组件被点击时，上报bav2b_click事件以及采集的参数大概如下

{
  event: 'bav2b_click',
  params: {
    path: 'pages/index/index',
    query_id: 'diandian',
    query_hi: 'hello'
  }
}

属性过滤
版本要求：2.12.0及以上
初始化参数增加clickIgnoreProperty，类型数组，在click设置为true的情况下有效，作用是过滤被点击元素的dataset值中相应的属性，比如设置了['abc', 'xxx']，那么所有被点击元素的属性上有abc或xxx的都会被过滤掉，不会采集。

• 全局设置

$$Rangers.init({
    // ...
    auto_report: {
        click: true,
        clickIgnoreProperty: ['imgSrc', '...'],
    }
});

• 单个元素设置

// 示例如下
<view bindtap="ontest" data-xxx="xxx-value" data-yyy="yyy-value" data-zzz="zzz-value" data-click-ignore-property="xxx,yyy"></view>

3.5 多实例使用方式

需要注意的是，不同实例的app_id需要不同。

// 导入sdk的类（构造器）
import SDK from '@datarangers/sdk-mp/esm/sdk';

// 对构造器使用new操作产生实例1
const $$Rangers1 = new SDK();
// 其他api调用完全一样
$$Rangers1.init({
    app_id: 1338,
});
$$Rangers1.config({});
$$Rangers1.send();

// 对构造器使用new操作产生实例2
const $$Rangers2 = new SDK();
// 其他api调用完全一样
$$Rangers2.init({
    app_id: 1339, // app_id不能与其他实例相同
});
$$Rangers2.config({});
$$Rangers2.send();

3.6 在飞书小组件中的使用方式

注意在飞书小组件场景下，不支持预置事件上报（即auto_report参数设置无效）。版本要求：2.9.0+

import Sdk from '@datarangers/sdk-mp/esm/block';
// 如果需要ab插件等功能，则需要手动加载插件
import AbPlguin from '@datarangers/sdk-mp/esm/plugin/ab';
Sdk.usePlugin(AbPlugin);
// 需要其他插件的功能的话，与上面ab插件的使用方式相同

const $$Rangers = new Sdk();
$$Rangers.init({
   //...
});
$$Rangers.config({});
$$Rangers.send();
// ....

3.7 多口径绑定处理

版本要求：2.11.0+，仅SaaS云原生、私有化支持。

// 示例中phone和email只是举例，具体传啥由业务决定
$$Rangers.bind({
    phone: '130xxxxxxxx',
    email: 'xxx@yyy.com'
}).then((status) => {
    // 业务根据status进行后续处理，可选处理
});

针对自动上报事件（app_launch、app_terminate等），SDK针对taro、uni-app第三方框架进行了兼容处理。此兼容需保证 SDK 版本高于 1.1.1。

4.1 taro框架使用方式

• 在 app.jsx 中通过 import 引入 SDK
• 在 App 类前初始化完成 SDK

4.2 uni-app框架使用方式

• 在 main.js 中通过 import 引入 SDK
• 在 App 类前初始化完成 SDK

4.3 预置事件上报排查

如果发现有部分自动事件未上报情况，可以按照下面几种情况排查：

• 尽可能的将SDK的初始化放在工程入口最前面；
• 第三方框架需要当前比较新的版本，taro、uni-app （其他第三方框架目前还未做特别兼容处理，有可能不支持）；
• 同时引入了其他类似功能的SDK，这种情况下尽量将我们的SDK放在其他SDK后面进行初始化（但是依然需要在App类前）。