You need to enable JavaScript to run this app.
导航

Web/JS SDK集成开发指南

最近更新时间2024.03.13 16:19:44

首次发布时间2022.01.17 11:23:03

一. 概述

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

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

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

二. 集成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 的脚本文件。

说明

对应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.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. 初始化 SDK

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}

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毫秒
})

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

注意

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

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以上支持

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

4. 用户与用户属性

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

5. 获取实验参数

「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作为内部处理进组用户的相关统计。

6. 上报实验指标(行为事件)

「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. API说明

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默认的赋值。

类型

字段

值类型

字段说明

实例

用户标识

user_unique_id

string

用户唯一标识。 没有设置 user_unique_id 时,则设置为 web_id。

业务方自行设置 * 设置为以下值时,会被忽略。 【'null', 'undefined', '0', '', 'None'】

公共属性

device_model

string

设备机型

3.3.4开始,针对移动端做简单的ua解析。如:(iphone/ipad/mi1 metal/SM-A8000/等)

公共属性

os_name

string

操作系统

sdk 默认上报:windows/mac/android/ios

公共属性

os_version

string

操作系统版本

sdk 默认上报

公共属性

platform

string

平台类型

默认上报 wap/web

公共属性

browser

string

浏览器名

默认上报

公共属性

browser_version

string

浏览器版本

默认上报

公共属性

language

string

浏览器语言

默认上报

公共属性

referrer

string

前向地址

默认上报

公共属性

referrer_host

string

前向域名

默认上报

公共属性

resolution

string

分辨率

默认上报

公共属性

screen_height

number

屏幕高度

默认上报

公共属性

screen_width

number

屏幕宽度

默认上报

公共属性

sdk_version

string

ByteFinder-sdk版本

默认上报

公共属性

timezone

int

时区

默认上报

公共属性

region

string

地域

业务方自行设置

公共属性

traffic_type

string

流量类型

公共属性

utm_source

string

推广来源

SDK默认采集

公共属性

utm_campaign

string

推广活动

SDK默认采集

公共属性

utm_medium

string

推广媒介

SDK默认采集

公共属性

utm_content

string

推广内容

SDK默认采集

公共属性

utm_term

string

推广关键词

SDK默认采集

系统占用

custom

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 事件预置属性

字段

类型

必传

说明

取值示例

url

string

当前页面地址

url_path

string

当前页面路径,不含协议和主机头部分

/tea/app/10000/behaviorDetail

title

string

页面标题

首页

time

number

时间戳

referrer

string

页面来源,document.referrer的值

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字段来计算进组人数,进组占比等等指标。 接口返回值:
图片
事件上报:
图片