实验(SuperSDK.experiment namespace)
A/B 实验能力 · H5 通过 SuperSDK.experiment.* 读取本设备所在的分组。实验在控制台「业务运营 → AB 实验」创建、启动与调整流量;分组由服务端按设备 ID 计算,SDK 不实现分流算法,只负责拉取本设备的结果、在本页面会话内固定读取结果、上报曝光,并在之后的每条埋点上带上已曝光的分组 ID。
只需记住一条:在用到的地方读,不要在启动时把所有实验读一遍。
get(key)默认就是「读取 + 曝光」,读过的实验会被记入实验数据;没看到变体的用户也被读取,会稀释组间差异。
| 环境 | 行为 |
|---|---|
纯浏览器(已 init(),analyticsConsent: 'granted') | init() 完成后立即拉取;设备 ID 取 SDK 的分析同意管理(与埋点同一个 deviceId) |
纯浏览器 · 未同意分析(analyticsConsent: 'denied') | 不发请求;get() 一律返回未参与,reason: 'no_subject' |
| 端内 · 容器支持实验 JSB(2.6.0 起,配套原生 SDK) | 委托原生:拉取、冻结、曝光与 exp_vids 全部由原生完成,与原生代码和其他 WebView 共享同一份结果、同一张冻结表和同一套曝光去重;H5 不发 assign 请求、不自己上报曝光。详见下方「端内:由原生托管」 |
| 端内 · 旧容器(未声明实验 JSB) | 保持网页拉取路径,设备 ID / spid / 环境 / 平台 / App 版本取自端内 getEnv();首次调用实验接口时才拉取 |
快速示例:
SuperSDK.init({ spid: 'ab12cd34', analyticsConsent: 'granted' });
// 首屏就要用实验时,先等结果(最多 1.5 秒,超时按默认值走)await SuperSDK.experiment.ready({ timeoutMs: 1500 });
const paywall = SuperSDK.experiment.get('paywall_price', { default: { price: '9.9' } });renderPaywall(paywall.payload.price); // 读取即上报曝光(SDK 去重)experiment.ready(options?)
Section titled “experiment.ready(options?)”等待本会话首个可用结果:本页面第一次拉取完成(成功或失败)即 resolve;到 timeoutMs 也 resolve,永不 reject 网络错误。未同意分析时立即 resolve。
| 参数 | 类型 | 说明 |
|---|---|---|
| options.timeoutMs | number | 最长等待毫秒数,默认 2000 |
| options.namespaces | string[] | 追加要加载的命名空间(^[a-z][a-z0-9_]{1,31}$)。默认只加载 default;含 default 合计最多 10 个。新增命名空间会立即重新拉取 |
返回值: Promise<void>;参数非法 reject INVALID_ARGUMENT。
超时后:已读过的 key 本会话保持默认值;未读过的 key 在结果到达后正常生效。
experiment.get(key, options?)
Section titled “experiment.get(key, options?)”同步读取实验结果。
const result = SuperSDK.experiment.get('paywall_price', { default: { price: '9.9' } });// 参与:// { inExperiment: true, variant: 'low', vid: 10388, payload: { price: '7.9' }, reason: 'alloc' }// 未参与:// { inExperiment: false, variant: '', vid: null, payload: { price: '9.9' }, reason: 'unknown' }| 参数 | 类型 | 说明 |
|---|---|---|
| key | string | 实验 key(控制台创建时填写) |
| options.default | object | 未参与时返回的 payload,默认 {} |
| options.expose | boolean | false 时只读取并冻结、不上报曝光,稍后用 expose(key) 补报。默认 true |
返回值: ExperimentResult
| 字段 | 类型 | 说明 |
|---|---|---|
| inExperiment | boolean | 是否参与(全量 rollout 也为 true) |
| variant | string | 分组 key;未参与为 '' |
| vid | number | null | 变体 ID(实验 × 轮次 × 分组,项目内唯一);未参与为 null |
| payload | object | 分组参数(控制台为分组填写的 JSON);未参与时为 options.default ?? {} |
| reason | string | 见下表 |
| reason | 含义 |
|---|---|
alloc | 按流量分配进入该分组 |
override | 命中强制名单 |
rollout | 实验已全量为该分组;不上报曝光、不计入 exp_vids |
unknown | 本设备的结果里没有这个实验(实验不存在、未运行、未命中受众或流量,客户端不区分);或这是服务端实验(见「服务端实验」) |
not_loaded | 该实验属于本页面尚未加载的命名空间(先 ready({ namespaces: [...] }));不冻结 |
no_result | 本地还没有结果(首次访问且结果未到 / SDK 未初始化),或结果超过 7 天未成功刷新 |
no_subject | 没有设备 ID(未同意分析) |
paused | 实验在本页面会话内被紧急停止(2.8.0 起,见下方「紧急停止」);不冻结、不曝光 |
冻结规则: 某个 key 在本页面第一次被 get 时,结果(包括未参与,not_loaded 除外)即固定到页面卸载;之后同一 key 一律返回同一结果,即使新结果已到达。冻结只对读取时的设备有效:撤回分析同意后返回 no_subject,重新同意(新的设备 ID)后按新设备的结果重新读取并冻结。新结果只影响本页面尚未读取过的 key,已读过的 key 在下次打开页面时生效。唯一例外是紧急停止。
紧急停止(2.8.0 起): 控制台对实验执行「紧急停止」后,拉取结果的 emergency_stopped 会列出该 key(只认被接受的完整响应;not_modified 响应与因 rules_version 较旧而丢弃的响应不处理,与原生一致)。SDK 收到后立即解除它的冻结:本页面之后的 get 返回未参与(reason: 'paused'、payload 为 options.default ?? {}),不再上报曝光;它的 vid 从已曝光集合中移除,之后创建的事件的 exp_vids 以及 getRequestHeaders() / appendVidsToUrl() / fetch() 都不再带它。每个 key 发一条诊断(onDiagnostic 收到 category: 'experiment'、code: 'EMERGENCY_STOPPED')。实验恢复运行后,本页面内该 key 仍保持停止,下次打开页面才重新读取到分组。端内委托原生时由原生处理:get 拿到原生的新结果(或 refresh() 重新镜像)后,页面内的值随之变为未参与。
曝光规则: 参与实验(alloc / override)时,get 自动上报一条 $exp_exposure 事件。同一变体每个页面会话最多一次、每个自然日最多一次(落盘去重),业务可以随意重复调用 get。未参与与 rollout 不上报。曝光事件经埋点通道上报,因此同样需要 analyticsConsent: 'granted'。
$exp_exposure 参数:
| 参数 | 说明 |
|---|---|
| vid | 变体 ID |
| exp_key | 实验 key |
| exp_run | 轮次 |
| exp_version | 实验配置版本 |
| variant | 分组 key |
| layer_key | 实验所在层 |
| reason | alloc / override |
| rules_version | 该结果对应的规则版本 |
| source | web(端内委托原生时由原生上报,为 h5) |
experiment.expose(key)
Section titled “experiment.expose(key)”为此前以 get(key, { expose: false }) 读取的实验补报曝光,上报的是读取时冻结的分组。用于必须提前读取、但用户未必会看到变体的场景(例如预加载资源)。未参与、rollout 或本页面未读取过该 key 时为无操作。
const banner = SuperSDK.experiment.get('home_banner', { expose: false });preload(banner.payload.image);// ……banner 真正出现在屏幕上时SuperSDK.experiment.expose('home_banner');experiment.getAll()
Section titled “experiment.getAll()”诊断与调试面板用:返回 { [key]: ExperimentResult & { type } },包含本设备当前参与的全部实验(客户端与服务端)与本页面已冻结的 key。type 为 'client' 或 'server'(2.7.0 起)。不冻结、不曝光;已冻结的 key 返回冻结值。业务逻辑必须用 get(key)。
experiment.refresh()
Section titled “experiment.refresh()”主动拉取一次。网络失败、限流时 reject(NETWORK_ERROR / TIMEOUT / RATE_LIMITED / UNAVAILABLE,本地结果照常可用);服务端拒绝(如 spid 不存在)reject INVALID_ARGUMENT 并带 nativeCode。
experiment.setAttributes(attributes)
Section titled “experiment.setAttributes(attributes)”设置自定义受众属性(对应控制台受众条件里的 attr.*),去抖 500ms 后重新拉取。
SuperSDK.experiment.setAttributes({ vip: '1', level: 12 }); // 上报为 attr.vip="1"、attr.level="12"SuperSDK.experiment.setAttributes({ vip: null }); // null / undefined 删除该属性- 键可写成
vip或attr.vip,只允许字母、数字、下划线,含attr.前缀不超过 64 字符;值为 string / number / boolean,转成字符串后不超过 256 字符;最多 20 个。不符合时同步抛INVALID_ARGUMENT。 - 属性只保存在当前页面内存中,不落盘;每次打开页面需要重新设置。
- SDK 自动携带的内置属性:纯浏览器
platform: 'web'与language(navigator.language原值);端内platform(android/ios)与app_version。
事件公参 exp_vids
Section titled “事件公参 exp_vids”曝光之后,SDK 在之后创建的每一条埋点事件上自动附带 exp_vids:本设备已曝光的变体 ID,升序、逗号分隔,例如 "10231,10388"。分析时可直接按它筛选(如 exp_vids like '%10388%')。
- 按事件创建时刻取值:曝光之前调用
reportEvent产生、尚在队列里未上传的事件不会带上之后曝光的 vid。 - 已曝光集合落盘保存,跨页面会话持续有效,直到该轮实验结束(拉取结果时服务端返回仍在进行的 vid 列表,已结束的自动移除)。
- 集合为空时不带该字段;最多 500 个,超出后新的 vid 不再加入(曝光事件照常上报,
onDiagnostic收到category: 'experiment', code: 'EXP_VIDS_LIMIT')。 exp_vids由 SDK 维护:reportEvent参数里与addEventCommonParam传入的同名字段会被忽略。
2.7.0 起。服务端实验(控制台类型「服务端」)的分组由业务后端使用:前端把本设备已曝光的变体 ID 集合随请求带给后端,后端据此走对应分支。值与事件公参 exp_vids 是同一个集合、同一个字符串(升序、逗号分隔),有两种携带方式:
- 请求头
X-Super-AB-Vids: 10231,10388,10412 - query 参数
super_ab_vids=10231,10388,10412(用于设不了请求头的场合:页面跳转、首屏文档请求、sendBeacon、EventSource、WebSocket 握手、表单提交、<img>/<script>)
await SuperSDK.experiment.ready({ namespaces: ['feed'] });
// 1. 用封装的 fetch:自动合并请求头(不改 URL)const res = await SuperSDK.experiment.fetch('https://api.example.com/feed', { method: 'POST', body });
// 2. 自己的网络库:取请求头后附加axios.get('/api/feed', { headers: { ...SuperSDK.experiment.getRequestHeaders() } });
// 3. 设不了请求头时用 query 参数location.href = SuperSDK.experiment.appendVidsToUrl('https://m.example.com/list?page=1');| 方法 | 说明 |
|---|---|
getRequestHeaders() | 同步返回 { 'X-Super-AB-Vids': '<vids>' };集合为空时返回 {}(不带该头) |
appendVidsToUrl(url) | 同步返回加上 super_ab_vids=<vids> 的 URL:已有同名参数则覆盖,保留其他参数与 #hash,相对地址保持相对;集合为空时原样返回。url 可传字符串或 URL,其他类型抛 INVALID_ARGUMENT |
fetch(input, init?) | 全局 fetch 的薄封装:参数与返回值同 fetch;把请求头合并进 init.headers(支持 Headers / 数组 / 普通对象,input 为 Request 且未传 init.headers 时以它的头为底),调用方已设置同名头时以 SDK 的为准;不改 URL |
曝光时机: 调用上面三个方法时,SDK 把已加载命名空间里本设备命中的全部服务端实验视为已读取:冻结到会话结束、上报 $exp_exposure(source 照常为 web,端内为 h5)、vid 加入已曝光集合,然后返回集合的字符串。同一会话内重复调用不重复曝光。所以服务端实验要放进对应业务的命名空间,只有该业务的页面 ready({ namespaces }) 加载并发送,避免把没走到实验逻辑的设备也计入。
get(key) 不读服务端实验: 读到服务端实验时返回未参与(reason: 'unknown'),不冻结、不曝光,onDiagnostic 收到 category: 'experiment', code: 'SERVER_EXPERIMENT_READ'(每个 key 一次)。getAll() 照常列出(type: 'server')。
SDK 自己发往平台的请求:网页路径下,本来就会触发 CORS 预检的 JSON POST 请求(实验 assign、埋点上传 reportEvent、监控上报、用户反馈)自动带 X-Super-AB-Vids,只带当前已曝光集合,不触发上面的「视为已读取」;集合为空时不带。配置拉取(settings GET)是 CORS 简单请求,不带该头,以免每次拉取多一次预检。端内经 JSB 交给原生的请求由原生 SDK 决定。
接入时必须知道的事:
- WebView 无法给页面自己发出的请求自动加请求头。 H5 发往自己后端的请求要用
experiment.fetch,或用getRequestHeaders()/appendVidsToUrl()自行附加;端内也是如此。SDK 不会自动改写任何业务 URL。 - 跨域请求会触发预检。 页面与后端不同源时,自定义请求头会让浏览器先发
OPTIONS,后端的Access-Control-Allow-Headers必须包含X-Super-AB-Vids,否则请求被浏览器拦截;不便改 CORS 时改用 query 参数。 - 后端读取顺序:请求头优先,其次 query 参数;两者都有且不一致时以请求头为准。
- 请求头与 query 参数可被用户篡改。 涉及价格、额度、权益的判断,后端不能只信它们,要用 device_id 调 assign(
side: "server")核验;仅影响展示或排序的实验可以直接读请求头。 - 结果尚未到达时值为空(首次启动、assign 未返回;端内
ready()之前),后端按默认逻辑处理。需要首个请求就带实验时,先await SuperSDK.experiment.ready()。 - 收尾顺序: 后端先把胜出逻辑改为默认并上线,再在控制台结束实验(服务端实验不支持「全量」,结束后 vid 会从集合里移除)。
- URL 长度: 接近 500 个 vid 时 query 参数很长,个别老旧代理有 2 KB 级的 URL 长度限制,能设请求头时优先用请求头。另外不要把参数加在可缓存的静态资源地址上(会让 CDN 缓存失效)。
端内:由原生托管
Section titled “端内:由原生托管”容器同时声明 experimentReady / getAllExperiments / getExperiment / exposeExperiment / setExperimentAttributes 五个 JSB 方法时(SuperSDK.bridge.supports(...),新协议 manifest 或旧桥上的同名函数均可),SuperSDK.experiment 自动委托原生,接口与返回值不变;同一页面一旦进入委托模式不再切回。
ready(options?):调用原生experimentReady(透传timeoutMs/namespaces),再用getAllExperiments把原生当前结果镜像到页面内存。永不 reject;原生失败时onDiagnostic收到category: 'experiment_native'。get(key, options?):仍是同步的——读镜像并在本页面冻结,同时异步调getExperiment让原生冻结并(默认)曝光。原生若已冻结了不同的结果(例如原生代码先读过),以原生的值为准:镜像与本页面冻结值随之修正,onDiagnostic收到code: 'NATIVE_RESULT_MISMATCH',之后的get返回原生值。ready()之前读取:返回未参与(reason: 'no_result')并在本页面冻结,且不通知原生(避免原生曝光一个页面没有展示的变体)——与网页端「结果到达前读取」一致。所以端内首屏要用实验时同样先await ready()。expose(key)→exposeExperiment;setAttributes(map)→setExperimentAttributes(校验规则同上,去抖与重拉由原生完成;属性在原生进程内共享,不再只属于当前页面)。getAll()返回镜像 + 本页面冻结值;refresh()重新读取原生当前结果(原生自行调度拉取:启动、回前台超过 10 分钟、改属性、切环境),失败时 reject。- 曝光与
exp_vids:曝光由原生上报,source为h5;端内所有埋点都经 JSBreportEvent交给原生,exp_vids由原生在事件创建时写入,JSSDK 不附带(调用方传入的同名参数照常丢弃)。 - 原生会话以 App 进程为界(退到后台超过 30 分钟视为新会话),而不是页面卸载;端内页面重新打开时,原生已冻结的实验仍返回同一结果。
- 服务端实验(2.7.0 起):
getAllExperiments的每项带type与exposed。getRequestHeaders()/appendVidsToUrl()/fetch()仍是同步的——用镜像算出值(已曝光的 vid + 命中的服务端实验 vid),同时异步调 JSBgetExperimentRequestVids让原生固定并曝光(source: 'h5'),之后以原生返回的集合为准(不一致时onDiagnostic收到code: 'NATIVE_RESULT_MISMATCH')。ready()之前返回空且不调用原生。容器未声明getExperimentRequestVids(旧原生 SDK)时只按镜像计算,onDiagnostic收到一次code: 'REQUEST_VIDS_UNSUPPORTED'。
拉取、缓存与同意
Section titled “拉取、缓存与同意”以下为网页路径(纯浏览器与旧容器)的行为;委托原生时由原生 SDK 负责。
- 拉取时机:
init()完成且有设备 ID 后立即拉取;页面从隐藏变为可见、且距上次成功拉取超过 10 分钟时再拉;setAttributes之后、ready({ namespaces })新增命名空间时、refresh()时。请求为POST {baseUrl}/v2/experiments/assign,与埋点使用同一组baseUrls(失败时轮转)并支持 suenc 响应解码。 - 本地缓存: 结果按 spid + 项目环境 + 设备 ID 存在
localStorage(键前缀supersdk_exp_v1:)。网络失败、限流时继续使用本地结果;本地结果超过 7 天未成功刷新视为无结果(no_result)。 - 同意: 分析同意为
denied时不发请求、get返回no_subject;setAnalyticsConsent('denied')会清空本地实验结果与已曝光集合,此前冻结的结果也不再返回;改为granted后立即重新拉取。 - 切换项目环境:
setAPIEnvironment()后使用新环境的独立缓存并重新拉取。