跳转到内容

实验(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 去重)

等待本会话首个可用结果:本页面第一次拉取完成(成功或失败)即 resolve;到 timeoutMs 也 resolve,永不 reject 网络错误。未同意分析时立即 resolve。

参数类型说明
options.timeoutMsnumber最长等待毫秒数,默认 2000
options.namespacesstring[]追加要加载的命名空间(^[a-z][a-z0-9_]{1,31}$)。默认只加载 default;含 default 合计最多 10 个。新增命名空间会立即重新拉取

返回值: Promise<void>;参数非法 reject INVALID_ARGUMENT。

超时后:已读过的 key 本会话保持默认值;未读过的 key 在结果到达后正常生效。

同步读取实验结果。

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' }
参数类型说明
keystring实验 key(控制台创建时填写)
options.defaultobject未参与时返回的 payload,默认 {}
options.exposebooleanfalse 时只读取并冻结、不上报曝光,稍后用 expose(key) 补报。默认 true

返回值: ExperimentResult

字段类型说明
inExperimentboolean是否参与(全量 rollout 也为 true)
variantstring分组 key;未参与为 ''
vidnumber | null变体 ID(实验 × 轮次 × 分组,项目内唯一);未参与为 null
payloadobject分组参数(控制台为分组填写的 JSON);未参与时为 options.default ?? {}
reasonstring见下表
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实验所在层
reasonalloc / override
rules_version该结果对应的规则版本
sourceweb(端内委托原生时由原生上报,为 h5)

为此前以 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');

诊断与调试面板用:返回 { [key]: ExperimentResult & { type } },包含本设备当前参与的全部实验(客户端与服务端)与本页面已冻结的 key。type 为 'client' 或 'server'(2.7.0 起)。不冻结、不曝光;已冻结的 key 返回冻结值。业务逻辑必须用 get(key)。

主动拉取一次。网络失败、限流时 reject(NETWORK_ERROR / TIMEOUT / RATE_LIMITED / UNAVAILABLE,本地结果照常可用);服务端拒绝(如 spid 不存在)reject INVALID_ARGUMENT 并带 nativeCode。

设置自定义受众属性(对应控制台受众条件里的 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。

曝光之后,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 决定。

接入时必须知道的事:

  1. WebView 无法给页面自己发出的请求自动加请求头。 H5 发往自己后端的请求要用 experiment.fetch,或用 getRequestHeaders() / appendVidsToUrl() 自行附加;端内也是如此。SDK 不会自动改写任何业务 URL。
  2. 跨域请求会触发预检。 页面与后端不同源时,自定义请求头会让浏览器先发 OPTIONS,后端的 Access-Control-Allow-Headers 必须包含 X-Super-AB-Vids,否则请求被浏览器拦截;不便改 CORS 时改用 query 参数。
  3. 后端读取顺序:请求头优先,其次 query 参数;两者都有且不一致时以请求头为准。
  4. 请求头与 query 参数可被用户篡改。 涉及价格、额度、权益的判断,后端不能只信它们,要用 device_id 调 assign(side: "server")核验;仅影响展示或排序的实验可以直接读请求头。
  5. 结果尚未到达时值为空(首次启动、assign 未返回;端内 ready() 之前),后端按默认逻辑处理。需要首个请求就带实验时,先 await SuperSDK.experiment.ready()。
  6. 收尾顺序: 后端先把胜出逻辑改为默认并上线,再在控制台结束实验(服务端实验不支持「全量」,结束后 vid 会从集合里移除)。
  7. URL 长度: 接近 500 个 vid 时 query 参数很长,个别老旧代理有 2 KB 级的 URL 长度限制,能设请求头时优先用请求头。另外不要把参数加在可缓存的静态资源地址上(会让 CDN 缓存失效)。

容器同时声明 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;端内所有埋点都经 JSB reportEvent 交给原生,exp_vids 由原生在事件创建时写入,JSSDK 不附带(调用方传入的同名参数照常丢弃)。
  • 原生会话以 App 进程为界(退到后台超过 30 分钟视为新会话),而不是页面卸载;端内页面重新打开时,原生已冻结的实验仍返回同一结果。
  • 服务端实验(2.7.0 起):getAllExperiments 的每项带 type 与 exposed。getRequestHeaders() / appendVidsToUrl() / fetch() 仍是同步的——用镜像算出值(已曝光的 vid + 命中的服务端实验 vid),同时异步调 JSB getExperimentRequestVids 让原生固定并曝光(source: 'h5'),之后以原生返回的集合为准(不一致时 onDiagnostic 收到 code: 'NATIVE_RESULT_MISMATCH')。ready() 之前返回空且不调用原生。容器未声明 getExperimentRequestVids(旧原生 SDK)时只按镜像计算,onDiagnostic 收到一次 code: 'REQUEST_VIDS_UNSUPPORTED'。

以下为网页路径(纯浏览器与旧容器)的行为;委托原生时由原生 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() 后使用新环境的独立缓存并重新拉取。