You need to enable JavaScript to run this app.
导航
Web/JS SDK集成
最近更新时间:2024.06.18 17:46:05首次发布时间:2022.01.17 11:23:03

概述

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

  • 实验组分流接口。
  • 指标上报(事件埋点上报)接口。
  • 和其他端不同,web/h5 做页面元素可视化编辑的相关实验(实验可视化实验,多变体可视化实验,多页可视化实验等),可能需要在实验参数返回前,对被实验页面或元素有进行遮罩,以免页面跳变影响用户体验。

该SDK支持编程实验、可视化实验,多链接实验,多变体可视化实验等客户端实验。

1. 集成SDK

注意

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

  • 如果已经集成了RangerAppLog web SDK 可以跳过此部分;
  • 如果没有,请参照下面:
    • 请注意5.0版本以上变量名称是LogAnalyticsObject,5.0之前版本为TeaAnalyticsObject
    • 同时请注意,你的版本必须大于等于V5.0.0

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

  • 定义了一个全局函数window.collectEvent,可以用来配置和发送事件。(为了避免与其他全局变量名冲突,collectEvent可以被替换为任意自定义的变量名)
  • 引入一段 SDK 的脚本文件。

说明

对应SDK的npm包可前往npm官网获取。

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.12.js"></script>

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

私有化版本需要获取js文件的私部地址,一般在{{domain}}/minio.byterangers.onpremise.docor.static/collect-privity-v5.1.12.js,如您不清楚此地址,请联系您的项目经理或客户成功经理。
如您使用私有化部署版本,请参照如下代码。

<script>    
(function(win, export_obj) {
    win['LogAnalyticsObject'] = export_obj;
    if (!win[export_obj]) {
        var _collect = function() {
            _collect.q.push(arguments);
        }
        _collect.q = _collect.q || [];
        win[export_obj] = _collect;                
    }
    win[export_obj].l = +new Date();
})(window, 'collectEvent');
</script>
<script async src="{{domain}}/minio.byterangers.onpremise.docor.static/collect-privity-v5.1.12.js"></script>

您也可使用火山提供的私部地址:

<script async src="https://lf3-data.volccdn.com/obj/data-static/log-sdk/collect/5.0/collect-privity-v5.1.12.js"></script>

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

2. 初始化SDK

2.1 获取appid

在开始集成前,首先需要在集团中拥有一个应用,请参考:如何创建应用

  • SaaS-云原生
    图片
  • SaaS-非云原生
    图片

2.2 获取数据上送地址

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

2.3 初始化SDK代码

2.3.1 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.3.2 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.3 私有化版本

如您使用私有化部署版本,请参照如下代码初始化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.4 配置完毕

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

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

2.5 使用调试工具

5.1.4以上的版本支持调试埋点,详细请查看调试工具
在初始化时设置以下参数:

window.collectEvent('init', {
  //....
  enable_debug: true // 上线前关闭此参数
})

同时在需要验证的页面URL后增加如下参数 (5.1.7以后的版本可以不加下面的参数):

?open_devtool_web=true&app_id=${appid} // 你的appid

3. 初始化基本配置

以下为常用初始化配置。配置时需参考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毫秒
    auto_exposure_expriment: false // boolean类型,按需开启,默认关闭,是否自动曝光全量实验 5.1.10版本支持
})

3.3 自动曝光全量

window.collectEvent('init', {
    enable_ab_test: true, // boolean类型,是否开启A/B实验功能
    auto_exposure_expriment: false // boolean类型,按需开启,默认关闭,是否自动曝光全量实验 5.1.10版本支持
})

开启后,SDK会根据下发的实验结果,自动曝光所有实验(除了多链接实验和可视化实验),不需要再额外调用getVar方法,5.1.10版本开始支持。

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 // 开启禁用PV上报的开关
})

3.6 内嵌H5页打通原生端(客户端)

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

// H5内嵌到原生端并打通
window.collectEvent('init', {
    // ...... 其他初始化配置
    enable_native: true 
    // 5.1.3以下版本参数为Native,
    // 5.1.3以上版本修改为enable_native,但仍然兼容了Native的设置
})

注意

⚠️ 请注意,原生端也需做初始化适配,请分别参考Android和iOS集成开发指南。

如果客户端初始化的时候采用了多实例的方式,可能会导致打通失败。有以下两种方式来调整:

  1. 客户端调用上报方式,使用默认实例初始化,不用多实例。
  2. H5页面手动绑定以下多实例的appid。在init方法之后,start方法之前调用如下代码。
window.collectEvent('setNativeAppId', appid)

3.7 初始化配置一览表

字段

是否必须

字段值

字段说明

示例/备注

app_id

预先申请。 number类型

业务产品的唯一标识

channel

可选值:cn,sg,va

上报通道标识。和channel_domain二选一。

国内,新加坡,美东

channel_domain

合法域名。字符串。

和channel二选一。设置该项后 channel 项会被忽略。 自定义上报的域名及其路径前缀。

https://xx.ccc.yy

ab_channel_domain

合法域名。字符串。

私有化域名
设置此参数时,ab实验获取域名则会根据此参数来获取。

https://xx.ccc.yy

log

布尔类型。默认false。

是否在控制台打印详细的 log 信息。

建议开启

enable_ab_test

布尔类型。默认false。

是否开启A/B实验功能

enable_ab_visual

布尔类型。默认false。

是否开启可视化实验
设置此参数时,ab实验读到可视化配置时会执行可视化逻辑
前提是必须开启enable_ab_test的总开关

enable_multilink

布尔类型。默认false。

是否开启多链接实验
注:开启多链接实验需要开启AB实验的前提,必须开启enable_ab_test的总开关

multilink_timeout_ms

number类型

多链接实验中默认的关闭遮罩层的时间
默认:500毫秒
前提是必须开启enable_ab_test的总开关

ebable_ab_test:true
enable_multilink: true,
multilink_timeout_ms:3000

disable_auto_pv

布尔类型。默认false。

是否禁止SDK上报默认PV

disable_sdk_monitor

布尔类型。默认false。

用于禁止SDK启动后自身监控事件的上报,(但目前并不会禁止错误日志的上报。)

autotrack

布尔类型。默认false。

开启无埋点上报。

具体能力请参考全埋点文档

enable_stay_duration

布尔类型。默认false。

开启停留时长。

具体请参考停留时长文档

cross_subdomain

布尔类型。默认false。

是否自动跨子域名识别用户,设置为true时多个子域名下使用同一浏览器访问的匿名用户会被自动识别为同一个用户,比如 a.yourdomain.com 和 b.yourdomain.com的情况。

cookie_domain

string类型

在开启上述配置后使用,可配置存储token或者utm参数的cookie域名,如你需要'a.bytedance.com'和'b.bytedance.com'串通,则传入'.bytedance.com',不传则默认存储在当前域名下

cookie_expire

number类型,默认7天(单位ms)

cookie过期时间

max_report

number类型,默认20

自定义埋点合并上报的条数

reportTime

number类型,默认30ms

埋点上报异步队列的时间间隔

configPersist

number类型,默认0

设置config参数是否需要持久化存储

0:不需要;1:session会话级存储;2:localstorage持久化存储

timeout

number类型,默认100000ms

埋点上报的超时时间

enable_native (5.1.3版本以下为Native)

boolean类型

是否走原生native sdk上报

开启后,所有的埋点和config设置都会通过原生native sdk完成

spa

boolean类型

是否开启路由变化的监控

开启后,当路由发生变化后,会重新上报PV和停留时长

disable_track_event

boolean类型

事件禁用参数

开启后,所有的埋点都不再上报

enable_custom_webid

boolean类型

是否使用自定义webid

allow_hash

boolean类型

是否支持监听hash路由

5.1.3以上支持

ab_cross

boolean类型

是否AB数据跨域名存储

5.1.3以上支持

ab_cookie_domain

string类型

AB数据跨域名存储开启后,存储的域名

5.1.3以上支持

disable_ab_reset

boolean类型

禁止切换uuid时的AB重置,注:切换uuid时,会清除之前uuid的缓存,并重发AB分流请求,在这个过程中,可能会造成vid不上报(uuid不匹配),请注意

5.1.4以上支持