字节跳动小程序SDK

1.1 安装SDK

使用npm方式安装

npm install @datarangers/sdk-mp

1.2 域名配置准备

在 「小程序后台-开发-开发设置-服务器域名」 中进行配置，具体可以参考小程序相应的官方文档，如微信小程序文档 https://developers.weixin.qq.com/miniprogram/dev/framework/ability/network.html

SaaS 业务：将https://mcs.volceapplog.com，https://abtest.volceapplog.com添加到小程序后台的“request合法域名”中。
私有化业务：将私有化部署的数据上报域名添加到小程序后台的“request合法域名”中，如您不清楚此域名，请联系您的项目经理或客户成功经理。

1.3 老版本升级

请注意，如果是SaaS业务，升级SDK到最新版（2.x.x版本）时，需要补充将https://mcs.volceapplog.com和https://abtest.volceapplog.com添加到小程序后台的“request合法域名”中，已添加过https://mcs.ctobsnssdk.com和https://toblog.ctobsnssdk.com不要立即移除。

1.4 旧版本说明

如果集成旧版本SDK(2.0以下版本)，需要将https://mcs.ctobsnssdk.com和https://toblog.ctobsnssdk.com 添加到微信开放平台的请求白名单中。

2.1 获取appid

在开始集成前，首先需要在集团中拥有一个应用。 「应用列表」-> 接入应用的「详情」->「应用ID」中可查看您的appid。

2.2 初始化 SDK示例

2.2.1 SaaS 业务

// 在入口页面初始化SDK
// app.js
import $$Rangers from '@datarangers/sdk-mp';
$$Rangers.init({
    app_id: 0000, // 替换成申请的app_id，参考2.1节获取，注意类型是number而非字符串
    log: true, // 开启后会控制台会打印日志，开发阶段有助于查看埋点上报过程
    auto_report: true, // 开启后会上报一些预定义事件，如app_launch、app_terminate等
    enable_ab_test: true, // 开启ab实验
});
$$Rangers.config({
    mp_name: 'xyz小程序', // 一些预定义属性，可以通过config进行设置mp_version: '1.1.1',
});
$$Rangers.send();
App({
    onLaunch: function () {
        this.$$Rangers = $$Rangers;
    
        // 如果想设置用户标识，比如想使用open_id来标识用户，可以在获取到open_id后把值设置给user_unique_id
        this.$$Rangers.config({
            user_unique_id: '获取到的open_id', //可以是open_id，也可以union_id等其他业务觉的可以用来标识用户唯一性的值
        });
        // 调用event方法上报具体事件
        this.$$Rangers.event('test_event', {
            from: 'launch', // 支持任意属性，值支持数字、字符串等
        });
    }
});
// 其他页面上报事件，如：
// pages/index/index.js
Page({
    onLoad() {
        getApp().$$Rangers.event('bind_view_tap', {
            'title': 'chart',
        });
    }
});

2.2.2 私有化业务

私有化业务需要明确设置数据上报域名，如您不清楚此域名，请联系您的项目经理或客户成功经理。

// 在入口页面初始化SDK
// app.js
import $$Rangers from '@datarangers/sdk-mp';
$$Rangers.init({
    app_id: 0000, // 替换成申请的app_id，参考2.1节获取，注意类型是number而非字符串
    channel_domain: "{{DOMAIN}}", // 设置私有化部署数据上送域名，如您不清楚此地址，请联系您的项目经理或客户成功经理
    log: true, // 开启后会控制台会打印日志，开发阶段有助于查看埋点上报过程
    auto_report: true, // 开启后会上报一些预定义事件，如app_launch、app_terminate等
    enable_ab_test: true, // 开启ab实验
    ab_channel_domain: "{{ABTEST_DOMAIN}}", // 设置ab分流接口域名，默认为channel_domain的设置
});
$$Rangers.config({
    mp_name: 'xyz小程序', // 一些预定义属性，可以通过config进行设置mp_version: '1.1.1',
});
$$Rangers.send();

App({
    onLaunch: function () {
        this.$$Rangers = $$Rangers;
    
        // 如果想设置用户标识，比如想使用open_id来标识用户，可以在获取到open_id后把值设置给user_unique_id
        this.$$Rangers.config({
            user_unique_id: '获取到的open_id', //可以是open_id，也可以union_id等其他业务觉的可以用来标识用户唯一性的值
        });
        // 调用event方法上报具体事件
        this.$$Rangers.event('test_event', {
            from: 'launch', // 支持任意属性，值支持数字、字符串等
        });
    }
});
 
// 其他页面上报事件，如：
// pages/index/index.js
Page({
    onLoad() {
        getApp().$$Rangers.event('bind_view_tap', {
            'title': 'chart',
        });
    }
});

3.1 登录态变化调用

3.1.1 账户登录

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

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

3.2 设置用户属性

3.2.1 profileSet

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

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

3.2.2 profileSetOnce

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

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

3.2.3 profileIncrement

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

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

3.2.4 profileAppend

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

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

3.2.5 profileUnset

删除用户的属性。

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

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

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

4.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），用于内部处理进组用户的相关统计。

4.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"}
        // }
    });
  }
});

5.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
});

5.2 事件公共属性

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

5.2.1 设置公共属性

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

6.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,
    // ...
});

6.2 config

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

示例

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

6.3 send

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

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

6.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: '...'
});

6.5 SDK预设公共属性字段

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

6.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",
        // }
    });
  }
});

6.7 自定义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页面。

6.8 预置事件自动上报

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

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

7.1 taro框架使用方式

• 在 app.jsx 中通过 import 引入 SDK

• 在 App 类前初始化完成 SDK

7.2 uni-app框架使用方式

• 在 main.js 中通过 import 引入 SDK

• 在 App 类前初始化完成 SDK

7.3 预置事件上报排查

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

• SDK版本需要1.1.1+，并且尽可能的将SDK的初始化放在工程入口最前面；

• 第三方框架需要当前比较新的版本，taro:、uni-app: （其他第三方框架目前还未做特别兼容处理，有可能不支持）；

• 同时引入了其他类似功能的SDK，这种情况下尽量将我们的SDK放在其他SDK后面进行初始化（但是依然需要在App类前）。

1. 为什么要调试实验

实验上线前需要保证前面的集成过程无误，上线后才能保证实验结果的科学和有效 ！

2. 开启调试状态

参照“创建实验”章节，使实验处于“调试中” 状态，如下图所示：

• 实验状态一共分三种：调试中、运行中、已结束。

3. 通过接口获取调试设备的统计口径

分别在微信小程序SDK init和config中打开日志和A/B Test开关，并完成初始化：

• 通过6.6中getToken方法获取对应的ssid

4. 添加至白名单

将您的测试设备 ssid 到白名单中，并在右下角点击"保存"按钮。

5. 微信小程序参数调试

设置完上述步骤后，清空缓存并编译，观察ab数据包（即abtest_config接口返回的实验数据），是否获取到了Tester 中的配置。下图中是成功获取到了实验参数：

如果您的微信小程序没有发出实验请求，或实验请求为空, 请按下面步骤排查：

• 初始化时是否正确设置 enable_ab_test: true；

• 微信小程序是否将“A/B Test域名”和“事件上报域名”添加到 微信开发者后台/开发/开发者设置/服务器域名 "request合法域名" 中，具体域名参考1.2～1.4章节。

触发实验事件后，您可以在事件数据包头观察到 ab_sdk_version 字段和内容（下图以ab_exposed事件举例，其他事件以此类推）：

6. 真机或模拟器实验场景调试

在实验参数调试正常的情况下，开发或者是QA/PM/运营 同学需要观察实验所在的页面是否符合之前实验设计的预期。

• 关于实验设计和准备，请参照“创建实验”章节。

1、当我需要创建客户端实验，但是想要关注服务端事件相关的指标，需要怎么上报服务端事件才能正常查看实验报告?

• 获取全部的实验 id

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"}
        // }
    });
});

• 传给服务端

• 调用http接口上报服务端事件时，需要在事件里带上客户端实验信息(ab_sdk_version)，具体事件上报格式参考HTTP API（服务端）