# @betterment-oss/test-track 中文文档 规范地址：https://npmcn.com/package/%40betterment-oss/test-track/ 版本：5\.0\.0 npm 元数据更新时间：2026-08-24T17:01:55.143Z 中文译文更新时间：2026-11-08T00:28:32.835Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40betterment-oss/test-track 原文对照：https://npmcn.com/package/%40betterment-oss/test-track/?lang=original 项目主页：https://github.com/Betterment/test_track_js_client#readme 源码仓库：https://github.com/Betterment/test_track_js_client ## 关键信息（来自 npm 元数据） - 包体积（解压后）：91 kB，9 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：3 个 - peer 依赖：vite \>=7\.0\.0 - 首次发布：2026-01-09T20:45:23.274Z - 最新版本发布：2026-08-24T17:01:54.952Z - 近 30 天下载量：3934（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：7（近 12 个月 7 个） ## 中文简介 测试音轨的 Javascript客户端 ## 安装 ```sh npm install @betterment-oss/test-track ``` 也可以使用：`pnpm add @betterment-oss/test-track`、`yarn add @betterment-oss/test-track`、`bun add @betterment-oss/test-track` ## README # TestTrack JS 客户端 这是 JavaScript 客户端库 [测试跟踪](https://github.com/Betterment/test_track) 系统. 它通过一个简单且多为宣示性的API提供客户端分化测试和特征取向. 这个图书馆旨在掩盖任务和访问者会议管理的细节,使你能够完全专注于访问者在被分配到一个变体时应取得的经验. 如果你想要完成服务器边的任务 并且你正在使用 Rails, 那就看看我们 [铁路客户端](https://github.com/Betterment/test_track_rails_client)。 。 。 . ## 安装 您可以通过 npm, 纱线或 pnpm 将测试音轨 js 客户端添加到您的应用程序中. ``` pnpm add @betterment-oss/test-track ``` 您可以找到最新版本的测试音轨 JS客户端 [这里](https://github.com/Betterment/test_track_js_client/releases)。 。 。 . ## 设置 设置TestTrack有两种方法: ### `load(options)` 从 TestTrack 服务器获取访问者配置并创建 TestTrack 实例 。 这是大多数使用案例的建议办法. ```javascript import { load, createCookieStorage } from '@betterment-oss/test-track'; const testTrack = await load({ client: { url: 'https://testtrack.example.com', appName: 'my_app', appVersion: '1.0.0', buildTimestamp: '2024-01-01T00:00:00Z' }, storage: createCookieStorage({ domain: '.example.com' }) }); ``` **参数:** - `client.url` - 您 TestTrack 服务器的 URL - `client.appName` - 你的申请名称 - `client.appVersion` - 您的应用程序版本 - `client.buildTimestamp` - 建造时间戳(ISO 8601格式) - `storage` - 长期访问者身份证的存储供应商(例如:. `createCookieStorage()`(中文(简体) ) - `analytics` (可选) - 跟踪任务的分析提供者(见 [高级配置](https://npmcn.com/package/%40betterment-oss/test-track/#readme-advanced-configuration)(中文(简体) ) - `errorLogger` (可选) - 记录错误的函数 ### `create(options)` 创建带有预装访问者配置的 TestTrack 实例 。 当您有可用的访问者配置数据(例如从服务器侧渲染或缓存响应)时使用此功能. ```javascript import { create, createCookieStorage } from '@betterment-oss/test-track'; const testTrack = create({ client: { url: 'https://testtrack.example.com', appName: 'my_app', appVersion: '1.0.0', buildTimestamp: '2024-01-01T00:00:00Z' }, storage: createCookieStorage({ domain: '.example.com' }), visitorConfig: { splits: [ { name: 'button_color', variants: [ { name: 'blue', weight: 50 }, { name: 'red', weight: 50 } ], feature_gate: false } ], visitor: { id: 'visitor-uuid', assignments: [{ split_name: 'button_color', variant: 'blue' }] }, experience_sampling_weight: 1 } }); ``` **参数:** - 与 `load()`,加上: - `visitorConfig` - 来自TestTrack API的预装访客配置数据 ## API 密码 #### `.visitorId` 返回当前访问者作为字符串的独特标识符 。 这种身份识别在存储提供者中一直存在,并用于维持连续的分会次任务. ```js console.log(testTrack.visitorId); // "abc123-def456-..." ``` #### `.vary(split_name, options)` 这个 `vary` 方法用于进行分割。 它需要2个参数并返回指定的变体作为字符串. - `split_name` - 第一个论点是分法的名称。 这将是一个蛇 case 字符串, 例如 . `"homepage_redesign_q1_2015"`。 。 。 . - `options` - 说吧 第二个参数是一个对象,包含: `context` 转让和默认变式(`defaultVariant`) (中文(简体) ). - `context` - 是开发者提供的字符串,以便测试音轨服务器能够记录最初创建任务的地方. 如果打给 `vary` 在一个以上的地方制造 用于给定的分块, 您可以看到哪个代码被先击中. - `defaultVariant` - 说吧 如果用户被分配到分拆中没有定义的变体,则使用默认变体. 发生这种情况后,Test Track会重新指派用户到默认变体. **你不应该依赖这种默认的行为, 它只是为了确保我们不打破客户的经验.** 相反,您应该确保拆分的所有变体在您的代码中处理,如果在后端的拆分中添加了变体,则更新您的代码以反映新的变体. 因为这种默认行为将用户重新指派给 `defaultVariant`,不记录未处理的变体的数据。 这将妨碍我们为分裂收集有意义的数据的能力. 这里有一个三分法的例子 `'control'` 是默认变体。 这么说吧 `'variant_4'` 在后端添加到此分页中, 但是这个代码没有更改来处理新变体 。 测试音轨指定的用户 `'variant_4'` 将重新分派到 `'control'`。 。 。 . ```js const variant = testTrack.vary('name_of_split', { context: 'homepage', defaultVariant: 'control' }); switch (variant) { case 'control': // do control stuff break; case 'variant_1': // do variant 1 stuff break; case 'variant_2': // do variant 2 stuff break; } ``` #### `.ab(split_name, options)` 这个 `ab` 方法专用于双向分拆和特征切换. 它需要两个参数,然后返回布尔值. - `split_name` - 第一个论点是分法的名称。 这将是一个蛇 case 字符串, 例如 . `"homepage_chat_bubble"`。 。 。 . - `options` - 说吧 第二个参数是一个对象,包含: `context` 和可选 `trueVariant`。 。 。 . - `context` - 是开发者提供的字符串,以便测试音轨服务器能够记录最初创建任务的地方. 如果打给 `vary` 在一个以上的地方制造 用于给定的分块, 您可以看到哪个代码被先击中. - `trueVariant` - 一个可选参数,指定哪个变体是"真"变体,另一个变体将作为默认. 没有真正的变体, `ab` 将假设拆分的变体被命名 `'true'` 财务报告和审定财务报表 `'false'`。 。 。 . ```js const hasVariantName = testTrack.ab('name_of_split', { context: 'homepage', trueVariant: 'variant_name' }); if (hasVariantName) { // do something } else { // do something else } ``` ```js const hasFeature = testTrack.ab('some_new_feature', { context: 'homepage' }); if (hasFeature) { // do something } ``` #### `.logIn(identifier, value)` 这个 `logIn` 采用这种方法是为了确保各种装置之间有一致的经验。 例如,当用户在新设备上登录到您的应用程序时,您也应该将用户登录到Test Track中,以便抓住他们现有的拆分任务,而不是像对待新访客一样对待他们. 这需要两个论点. - `identifier` - 说吧 第一个论据是标识符的名称. 这将是一个蛇 case 字符串, 例如 . `"myapp_user_id"`。 。 。 . - `value` - 说吧 第二个参数是一个字符串值,例如. `"12345"`, (中文(简体) ), `"abcd"` ```js await testTrack.logIn('myapp_user_id', '12345'); // From this point on you have existing split assignments from a previous device. ``` ## 高级配置 当你打电话 `load()` 或者说 `create()` 您可以在分析对象和错误日志中选择通过。 例如: ```js const testTrack = await load({ client: { url: 'https://testtrack.example.com', appName: 'my_app', appVersion: '1.0.0', buildTimestamp: '2024-01-01T00:00:00Z' }, storage: createCookieStorage({ domain: '.example.com' }), analytics: { trackAssignment: (visitorId, assignment) => { const props = { SplitName: assignment.splitName, SplitVariant: assignment.variant, SplitContext: assignment.context }; remoteAnalyticsService.track('SplitAssigned', props); }, identify: visitorId => { remoteAnalyticsService.identify(visitorId); }, alias: visitorId => { remoteAnalyticsService.alias(visitorId); } }, errorLogger: message => { RemoteLoggingService.log(message); // logs remotely so that you can be alerted to any misconfigured splits } }); ``` ## 测试 创建测试跟踪实例, 用于预配置任务测试, 没有网络请求 . ```javascript import { stub } from '@betterment-oss/test-track'; const testTrack = stub({ button_color: 'blue', new_feature_enabled: 'true' }); testTrack.vary('button_color', { context: 'test', defaultVariant: 'red' }); // 'blue' testTrack.ab('new_feature_enabled', { context: 'test' }); // true ``` ## 类型脚本 TestTrack 支持根据您的项目计划进行严格的类型检查 . ```typescript import { load } from '@betterment-oss/test-track'; import type Schema from './path/to/your/schema.json'; // Pass `Schema` as a type parameter const testTrack = await load({ /* ... */ }); // Split names and variants are now type-checked testTrack.vary('button_color', { context: 'home', defaultVariant: 'blue' }); testTrack.ab('new_feature_enabled', { context: 'home' }); ``` ## 虚拟插件 这个 `@betterment-oss/test-track` 软件包包括自动定义的 Vite 插件 `import.meta.env.TT_BUILD_TIMESTAMP`,用于配置测试音轨. ```ts import { defineConfig } from 'vite'; import { testTrackPlugin } from '@betterment-oss/test-track/vite'; export default defineConfig({ plugins: [testTrackPlugin()] }); ``` ## 使用没有构建工具的 TestTrack 这个 `@betterment-oss/test-track` 软件包作为ES模块分发。 该套件还提供了 `dist/index.iife.js`。该文物包括所有依赖性,可以直接用于浏览器. ```html ``` ## 如何贡献 我们非常希望你能出力! 任何有利于大多数人的 `test_track` 鼓励用户——从文档修补到全新的功能. 在潜入之前, [检查我们的问题追踪器](https://github.com/Betterment/test_track_js_client/issues) 并且考虑创建一个新问题,以便早日获得对您提议的修改的反馈. ### 二. 建议的工作流程 1. 将项目叉开,为您的贡献创建一个新的分支. 2. 填写您的贡献( 以及任何适用的测试范围) . 3. 确保所有测试通过. 4. 提交拉动请求 . ### 正在测试 1. 运行 `pnpm install` 下载依赖关系 2. 运行 `pnpm test` 运行测试 3. 运行 `pnpm build` 建造可分配物 ## 常见问题 ### @betterment-oss/test-track 是什么？ 测试音轨的 Javascript客户端 ### 如何安装 @betterment-oss/test-track？ 在项目目录运行 npm install @betterment-oss/test-track，或使用 pnpm add / yarn add / bun add。 ### @betterment-oss/test-track 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @betterment-oss/test-track 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @betterment-oss/test-track 可以商用吗？ @betterment-oss/test-track 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @betterment-oss/test-track 的下载量有多少？ 根据 npm 官方下载统计，@betterment-oss/test-track 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,934 次，日均约 131 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @betterment-oss/test-track 还在维护吗？ 最新版本 5\.0\.0 发布于 2026/08/25（2 个月前）；至今共发布 7 个版本，其中过去 12 个月发布了 7 个；首次发布于 2026/01/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。