1.1 登录态变化调用

1.1.1 账户登录

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

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

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');

版本1.0.9开始，sdk增加了ab实验能力，提供了getVar、getAllVars等方法，这些方法在开启ab实验时才有效，即enable_ab_test: true。「A/B 测试」通常在SDK 初始化后会向分流服务发送一个分流请求（request），在获取到分流服务的响应（response）后，客户端开发可以根据分流的结果参数完成代码分支。

• 请注意此步骤的前置条件：已经根据实验的需求方创建好了实验及相关的参数，具体见“创建实验”。

2.1 getVar

获取ab实验元信息中的变量对应的值。 一个变量name是和一个vid绑定的，获取成功之后，会把对应的vid设置到sdk上报的公共属性里。

App({
  onLaunch: function () {
    this.$$Rangers = $$Rangers; // 绑定到全局的app，以便其他页面调用。
    //experiment-key 为实验参数的key ，用户开发做代码分支，default-value 为网络异常时的兜底方案，建议和对照组value一致
    this.$$Rangers.getVar('experiment-key', 'defaulte-value', function(value) {
        console.log(value);
    });
    //示例
    this.$$Rangers.getVar('size', '1', function(value) {
        console.log(value);
    });
  }
});

当调用getVar 的方法会自动上报曝光事件（ab_exposure），用于内部处理进组用户的相关统计。

2.2 getAllVars

如果需要获取所有ab实验的进组信息可使用getAllVars方法，但是此方法不会上报曝光事件，因此调用此方法系统不会有数据显示，只做获取进组信息接口使用。

App({
  onLaunch: function () {
    this.$$Rangers = $$Rangers; // 绑定到全局的app，以便其他页面调用。
    this.$$Rangers.getAllVars(function(data) {
        //data数据格式如下：
        // {
        //   "aa": {"vid": "1183", "val": true},
        //   "test_before_6d": {"vid": "2446", "val": "fail"}
        // }
    });
  }
});

3.1 上报代码埋点

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

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

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

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

3.2 事件公共属性

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

3.2.1 设置公共属性

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

4.1 init

支持的初始化参数

示例

// 参数：InitParams
// 返回值：void
$$Rangers.init({
    app_id: 1338,
    log: true,
    auto_report: true,
    enable_ab_test: true,
    clear_ab_cache_on_user_change: true,
    // ...
});

4.2 config

config方法可以调用多次，后面设置会覆盖之前相同的属性字段

示例

// 参数：ConfigParams
// 返回值：void
$$Rangers.config({
    city: '南京',
    custom_name: 'vikings',
    // ...
});

4.3 send

当初始化设置完毕之后，必须调用send方法，sdk才真正初始化完毕，之前不会有数据上报。 示例

// 参数：无
// 返回值：void
$$Rangers.send();

4.4 event

进行事件上报。 事件命名规范：

• 事件命名仅支持字母、数字和下划线，不要使用app_launch、app_terminate等SDK内部自动上报事件名
• 建议事件名和属性统一使用小写
• 事件属性值仅接受number与string类型
• 不要在事件属性中再嵌套object，即属性值不接受object类型
• 如果想要表达事件属性值空的含义，建议用“be_null”，不建议使用""或" "

示例

// 参数：name: string, params: object
// 返回值：void
$$Rangers.event('start_event', {
    start_time: 1630986183813,
    path: '...'
});

4.5 SDK预设公共属性字段

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

4.6 获取平台生成的各种ID

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

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

4.7 获取实验版本ID

$$Rangers.getAbSdkVersion();

4.8 自定义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的值要求纯数字或全是数字的字符串类型
});

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

4.9 预置事件自动上报

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

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

5.1 taro框架使用方式

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

5.2 uni-app框架使用方式

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

5.3 预置事件上报排查

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

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