Web/JS SDK集成开发指南

「A/B 测试」 在 Web/H5/WAP 端不提供单独的SDK，而是依赖增长营销套件SDK 中的A/B Test 相关接口。增长营销套件 SDK 主要的和A/B Test 相关接口有两个：

• 实验组分流接口。

• 指标上报（事件埋点上报）接口。

• 和其他端不同，web/h5 做修改页面元素的实验（可视referrer化实验）时， 可能需要在实验参数返回前，对被实验页面或元素有进行遮罩，以免页面跳变影响用户体验。

该SDK支持编程实验、可视化实验和多链接实验。

注意：此文档针对5.0版本以上的SDK阅读

• 如果已经集成了RangerAppLog web SDK 可以跳过此部分；

• 如果没有，请参照下面：

• 请注意5.0版本以上变量名称是LogAnalyticsObject，5.0之前版本为TeaAnalyticsObject

• 同时请注意，你的版本必须大于等于V5.0.0

1. 初始化 SDK

复制对应的代码片段，放到标签内尽可能靠前的位置。如您使用SaaS版本，请参考1.1节；如您使用私有化版本，请参考1.2节。这段代码的作用是：

• 定义了一个全局函数window.collectEvent，可以用来配置和发送事件。（为了避免与其他全局变量名冲突，collectEvent可以被替换为任意自定义的变量名）

• 引入一段 SDK 的脚本文件。

1.1 安装代码 (SaaS版本)

如您使用SaaS部署版本，请参照如下代码。

<script>    
(function(win, export_obj) {
    win['LogAnalyticsObject'] = export_obj;
    if (!win[export_obj]) {
        function _collect() {
            _collect.q.push(arguments);
        }
        _collect.q = _collect.q || [];
        win[export_obj] = _collect;                
    }
    win[export_obj].l = +new Date();
})(window, 'collectEvent');
</script>
<script async src="https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-rangers-v5.1.6.js"></script>

1.2 安装代码 (私有化版本)

如您使用私有化部署版本，请参照如下代码。

<script>    
(function(win, export_obj) {
    win['LogAnalyticsObject'] = export_obj;
    if (!win[export_obj]) {
        function _collect() {
            _collect.q.push(arguments);
        }
        _collect.q = _collect.q || [];
        win[export_obj] = _collect;                
    }
    win[export_obj].l = +new Date();
})(window, 'collectEvent');
</script>
<script async src="https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-rangers-v5.1.6.js"></script>

如果不能远程集成，请联系您的项目经理或客户成功经理，也可以直接把上方js文件下载下来做离线引入。

2.1 获取appid

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

2.2 获取数据上送地址

私有化部署版本需要获取数据上送地址。
如您不清楚此地址，请联系您的项目经理或客户成功经理。

2.3 初始化SDK

2.3.1 SaaS版本

如您使用SaaS部署版本，请参照如下代码初始化SDK。

window.collectEvent('init', {
    app_id: {{APPID}}, // 参考2.1节获取，注意类型是number而非字符串
    channel: 'cn', // 设置数据上送地址
    log: true, // true:开启日志，false:关闭日志
    autotrack: false, // 全埋点开关，true开启，false关闭
    enable_ab_test: true, // boolean类型，是否开启A/B实验功能
    enable_ab_visual: false, // boolean类型，按需开启，默认关闭，是否开启A/B实验的可视化编辑模式功能
    enable_multilink: false, //boolean类型，按需开启，默认关闭，是否开启A/B实验的多链接实验功能，默认为false
    multilink_timeout_ms:1000 //number类型，A/B实验的多链接实验中关闭遮罩层的时间，默认500毫秒
});
// 此处可添加设置uuid、设置公共属性等代码
window.collectEvent('start'); // 通知SDK设置完毕，可以真正开始发送事件了

2.3.2 私有化版本

如您使用私有化部署版本，请参照如下代码初始化SDK。

window.collectEvent('init', {
    app_id: {{APPID}}, // 参考2.1节获取，注意类型是number而非字符串
    channel_domain: '{{REPORT_URL}}', // 设置私有化部署数据上送地址，参考2.2节获取
    ab_channel_domain: '{{REPORT_URL}}' // 设置私有化域名，通常为数据上送地址，参考2.2节获取
    log: true, // true:开启日志，false:关闭日志
    autotrack: false, // 全埋点开关，true开启，false关闭
    enable_ab_test: true, // boolean类型，是否开启A/B实验功能
    enable_ab_visual: false, // boolean类型，按需开启，默认关闭，是否开启A/B实验的可视化编辑模式功能
    enable_multilink: false, //boolean类型，按需开启，默认关闭，是否开启A/B实验的多链接实验功能，默认为false
    multilink_timeout_ms:1000 //number类型，A/B实验的多链接实验中关闭遮罩层的时间，默认500毫秒
});
// 此处可添加设置uuid、设置公共属性等代码
window.collectEvent('start'); // 通知SDK设置完毕，可以真正开始发送事件了

2.3.3 SaaS云原生版本

如您使用SaaS云原生部署版本，请参照如下代码初始化SDK。

window.collectEvent('init', {
    app_id: {{APPID}}, // 参考2.1节获取，注意类型是number而非字符串
    channel_domain: 'https://gator.volces.com', // 设置数据上送地址
    ab_channel_domain: 'https://tab.volces.com', // 分流请求域名
    log: true, // true:开启日志，false:关闭日志
    autotrack: false, // 全埋点开关，true开启，false关闭
    enable_ab_test: true, // boolean类型，是否开启A/B实验功能
    enable_ab_visual: false, // boolean类型，按需开启，默认关闭，是否开启A/B实验的可视化编辑模式功能
    enable_multilink: false, //boolean类型，按需开启，默认关闭，是否开启A/B实验的多链接实验功能，默认为false
    multilink_timeout_ms:1000 //number类型，A/B实验的多链接实验中关闭遮罩层的时间，默认500毫秒
});
// 此处可添加设置uuid、设置公共属性等代码
window.collectEvent('start'); // 通知SDK设置完毕，可以真正开始发送事件了

2.4 配置完毕

初始化结束后，需要通知SDK设置完毕，可以真正开始发送事件了。
说明： start方法调用前，同样可以上报事件，这些事件被缓存在内存中，没有真正的发送给服务端；直到start调用后，缓存的事件才会与设置的用户属性等参数合并成完整的事件结构，然后通过网络请求发送给服务端。start方法调用后发送的事件，则直接合并参数后然后发给服务端。

// 必须在初始化配置完成后，加入这行代码，否则SDK不会发送数据
window.collectEvent('start');

2.5 使用调试工具

5.1.4以上的版本支持本地/线上直接调试埋点，详细请查看调试工具。
需要验证的页面URL后增加如下参数：

?open_devtool_web=true&app_id=${appid}

以下为常用初始化配置。配置时需参考2.3/2.4节，添加到window.collectEvent('init', {/ ... /})中。

3.1 全埋点设置开关

全埋点开关默认关闭。

// 开启全埋点功能
window.collectEvent('init', {
    // ...... 其他初始化配置
    autotrack: true
})

3.2 查看日志打印

日志打印默认关闭。

// 在控制台打印详细的log信息，协助排查
window.collectEvent('init', {
    // ...... 其他初始化配置
    log: true
})

3.3 AB功能相关

window.collectEvent('init', {
    enable_ab_test: true, // boolean类型，是否开启A/B实验功能
    enable_ab_visual: false, // boolean类型，按需开启，默认关闭，是否开启A/B实验的可视化编辑模式功能
    enable_multilink: false, //boolean类型，按需开启，默认关闭，是否开启A/B实验的多链接实验功能，默认为false
    multilink_timeout_ms:1000 //number类型，A/B实验的多链接实验中关闭遮罩层的时间，默认500毫秒
})

3.4 禁止AB数据重置

是否在变更user_unique_id时，禁止AB数据的重置。通常用于匿名状态转为实名状态。多用户之间切换，请不要开启。

window.collectEvent('init', {
    disable_ab_reset: true | false 默认false
})

3.5 关闭pv事件上报

当访问页面时，SDK会默认上报一次pv事件(事件名predefine_pageview)，此预置事件默认上报。如需关闭，请在初始化配置中禁用此事件。

// 在控制台打印详细的log信息，协助排查
window.collectEvent('init', {
    // ...... 其他初始化配置
    disable_auto_pv: true
})

3.6 内嵌H5页打通原生端

原生端开启内嵌H5页打通后，内嵌H5页上产生的事件将通过原生端SDK上报，不在js SDK上报，并复用原生端设置的user_unique_id和公共属性。此时，还需在集成js sdk的H5页上开启打通开关。

// H5内嵌到原生端并打通
window.collectEvent('init', {
    // ...... 其他初始化配置
   enable_native: true
})

3.7 初始化配置一览表

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

4.1 登录态变化调用

4.1.1 账户登录

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

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

4.1.2 账户登出

在账户登出时调用。

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

4.2 设置用户属性

4.2.1 profileSet

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

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

4.2.2 profileSetOnce

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

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

4.2.3 profileIncrement

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

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

4.2.4 profileAppend

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

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

4.2.5 profileUnset

删除用户的属性。

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

「A/B 测试」通常在SDK 初始化后会向分流服务发送一个分流请求（'/service/2/abtest_config/'），在获取到分流服务的结果后，客户端开发可以根据分流的结果参数完成代码分支。

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

window.collectEvent('getVar', 'ab-key', 'ab-default-value', (value) => { 
//ab-key 为实验参数的 key ，用户开发做代码分支，ab-default-value 为异常时的兜底方案，建议和对照组 value 一致
// 以下为业务代码
window.collectEvent('发送业务指标事件')
   })

getVar是一个异步方法，getVar的回调只有在ab实验结果返回之后才会执行，所以如果想要业务自定义的事件指标也能带上ab_sdk_version，那么需要在getVar的回调中调用业务自定义事件。完整代码如下：

window.collectEvent('getVar', 'abcdefg', 'default', (res)=> {
   window.collectEvent('自定义事件')
   // 这样，你的自定义事件上报时就会有对应的ab_sdk_version
})

注意：在web端和小程序中，「A/B 测试」在调用getVar成功后，会自动上报一个曝光事件（abtest_exposure），如果业务并没有自定义的指标事件作为统计，可以使用abtest_exposure作为内部处理进组用户的相关统计。

「A/B 测试」 中的实验指标计算依赖Finder中的事件日志，示例代码如下：

• 也可参见Finder SDK 集成文档 “上报埋点日志” 部分：

6.1 上报事件

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

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

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

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

6.2 事件公共属性

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

6.2.1 设置公共属性

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

6.3 页面跳转前上报埋点

请注意，在埋点设计时，不建议在发送事件后紧接着进行页面跳转。这种情况下，上报请求可能会失败，统计数据可能缺失。请考虑以下两种方式之一：
1）使用beconEvent。
beconEvent会将埋点通过浏览器的特性sendbeacon来发送，尽可能补偿数据上报。

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

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

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

7.1 config(paramsObj)

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

• 需在 init 之后调用

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

• 参数为一个对象

  • 参数分类：

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

    • 用户标识相关字段

    • 用户属性（公共属性），

      • 预设

      • 自定义

    • 事件共有的事件属性

// 1. 第1次调用，此时发送的事件都包含 cn ， Monday

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

window.collectEvent('config', {
    language: 'en',
})

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

7.2 页面浏览事件

7.2.1 SDK 默认调用

predefine_pageview事件默认调用，如需关闭，请参考3.4节。

7.2.2 业务手动调用

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

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

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

7.2.3 事件预置属性

7.2.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")
}

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

7.4 自定义webid

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

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

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

7.5 打开遮罩层

在页面上打开一个全局的遮罩层（相当于白屏），当你需要用AB实验修改页面的UI时，防止用户看到明显的UI变化，可以进行使用。注，当你手动打开遮罩层后，一定记得手动关闭。
开启遮罩层

window.collectEvent('openOverlayer')

关闭遮罩层

window.collectEvent('closeOverlayer')

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

• 获取全部的实验 id

window.collectEvent('getAllVars', function(data) { 
    //data数据格式如下：//{//  "aa": {"vid": "1183", "val": true}, //  "test_before_6d": {"vid": "2446", "val": "fail"}//}
})

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

2、实验指标是如何计算的？
实验指标计算依赖事件上报时数据中的ab_sdk_version字段，对应的则是ab实验返回值中的vid。 服务端会根据用户上报的ab_sdk_version字段来计算进组人数，进组占比等等指标。 接口返回值：

事件上报：