更新记录

1.0.1（2026-10-15） 下载此版本

增加自定义实验参数

1.0.0（2026-09-15） 下载此版本

• 初始版本：init + fetchCacheABTest / asyncFetchABTest / fastFetchABTest
• 本地缓存三重校验、定时轮询、QT 埋点曝光
• 支持 H5 / APP / 微信小程序

平台兼容性

uni-app(4.85)

uni-app x(4.85)

wl-AbTest

Uni-app 跨平台 ABTest 前端 SDK，支持 H5、APP、微信小程序。

外部接入请参阅 INTEGRATION.md（完整接入指南 v1.0.0）。

功能

• ABTestSDK.init() 初始化实例（不自动请求分流接口）
• fetchCacheABTest 同步读缓存
• asyncFetchABTest 异步强制请求
• fastFetchABTest 缓存优先
• 本地缓存三重校验（存在性 / 身份 / 时间）
• 定时轮询 + 页面可见性暂停
• QT 埋点曝光（ABTestExpTriggerOnce / ABTestExpTrigger）

环境配置

编辑 constants/env.ts 配置各环境分流服务地址：

export const ABTEST_GATEWAY_PREFIX = '/gateway/canary-engine-server'
export const ABTEST_API_BASE = {
  prod: 'https://xinggui.wlydmarket.com',
  uat: 'https://xinggui-uat.10000da.vip',
  dev: 'https://xinggui-dev.10000da.vip',
  test: 'https://xinggui-test.10000da.vip',
  mock: 'https://m1.apifoxmock.com/m1/7421417-7154856-default',
}
export const ASSIGN_PATH = `${ABTEST_GATEWAY_PREFIX}/engine/v1/assignment`

初始化

import ABTestSDK, { adaptWlydTrack } from '@/uni_modules/wl-AbTest'

// APP 端（QT 初始化后）
const abtest = ABTestSDK.init({
  projectId: '123',
  qtInstance: uni.$QtAnalytics,
  env: 'prod',
  enableLog: true,
  updateTime: 600000,
  userId: '2016067789495398400',
  onABTestResultChange: () => console.log('ABTest result changed'),
  onError: err => console.error(err),
})
uni.$AbTest = abtest

// 微信小程序
const abtestMp = ABTestSDK.init({
  projectId: '123',
  qtInstance: adaptWlydTrack(wx.$wlydTrack),
  env: 'dev',
})

// init 后通过 fetch / setUserId 触发分流请求
uni.$AbTest.fetchCacheABTest({
  paramName: 'card_style',
  valueType: 'STRING',
  defaultValue: 'style_a',
})

// 登录/异步拿到 userId 后
await uni.$AbTest.setUserId('2016067789495398400')

调用示例

// 通用场景：缓存优先
uni.$AbTest.fastFetchABTest({
  paramName: 'checkout_button_color',
  valueType: 'STRING',
  defaultValue: '#1890ff',
  autoExposure: true,
  callback(result) {
    buttonColor.value = result
  },
})

// 低延迟：仅读缓存
uni.$AbTest.fetchCacheABTest({
  paramName: 'button_color',
  valueType: 'STRING',
  defaultValue: 'red',
  callback(result, $sendPV, data) {
    console.log(result, data?.expid, data?.gid)
  },
})

// 需要最新数据（带自定义分流参数）
await uni.$AbTest.asyncFetchABTest({
  paramName: 'feature_flag',
  valueType: 'BOOLEAN',
  defaultValue: false,
  customIds: { driver_id: '123', vehicle_id: '456', freight_id: '789' },
  customProperties: { country: 'CN', city: 'Hangzhou' },
  autoExposure: false,
  callback(result, $sendPV) {
    enabled.value = result
    // 业务手动曝光
    $sendPV?.()
  },
})

Vue Composable

import { useAbTest } from '@/uni_modules/wl-AbTest/composables/useAbTest'

const { fastFetchABTest } = useAbTest()

valueType 说明

注意事项

1. 任何异常均静默返回 defaultValue，不会抛错
2. init() 仅创建实例；asyncFetchABTest / fastFetchABTest 首次调用后会自动启动轮询；setUserId() 默认会重新拉取分流并重启轮询
3. customIds 默认键为 driver_id（司机）、vehicle_id（车辆）、freight_id（货源），也可传其他键；customIds / customProperties 仅在网络请求时携带；fetchCacheABTest 忽略这两个参数；fastFetchABTest 仅在缓存未命中走网络时携带
4. customIds 或 customProperties 任一非空时，网络请求结果不会写入本地缓存
5. 轮询失败会指数退避重试；asyncFetch / fastFetch 失败直接返回 defaultValue
6. 接口响应格式：{ succeed, code, message, model: { expContext } }，变量名对应 params[].paraKey
7. 埋点事件：ABTestExpTriggerOnce（同用户+实验+实验组+相同 para_key 且 paramName 与接口 paraKey 一致时仅上报一次）、ABTestExpTrigger（每次 fetch 结果都上报）；参数：trigger_mode / trigger_time / user_id / device_id / experiment_id / group_id / crowd_id / is_debug / para_key / project_id；走网络且存在 custom 参数时额外携带 custom_ids / custom_properties（JSON 字符串）
8. 联调前请在 constants/env.ts 替换真实 API 地址