TestTrack JS 客户端

这是 JavaScript 客户端库 测试跟踪 系统.

它通过一个简单且多为宣示性的API提供客户端分化测试和特征取向.

这个图书馆旨在掩盖任务和访问者会议管理的细节,使你能够完全专注于访问者在被分配到一个变体时应取得的经验.

如果你想要完成服务器边的任务 并且你正在使用 Rails, 那就看看我们 铁路客户端。 。 。 .

安装

您可以通过 npm, 纱线或 pnpm 将测试音轨 js 客户端添加到您的应用程序中.

pnpm add @betterment-oss/test-track

您可以找到最新版本的测试音轨 JS客户端 这里。 。 。 .

设置

设置TestTrack有两种方法:

load(options)

从 TestTrack 服务器获取访问者配置并创建 TestTrack 实例 。 这是大多数使用案例的建议办法.

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 (可选) - 跟踪任务的分析提供者(见 高级配置(中文(简体) )
• errorLogger (可选) - 记录错误的函数

create(options)

创建带有预装访问者配置的 TestTrack 实例 。 当您有可用的访问者配置数据(例如从服务器侧渲染或缓存响应)时使用此功能.

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

返回当前访问者作为字符串的独特标识符 。 这种身份识别在存储提供者中一直存在,并用于维持连续的分会次任务.

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'。 。 。 .

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'。 。 。 .

  const hasVariantName = testTrack.ab('name_of_split', { context: 'homepage', trueVariant: 'variant_name' });
  
  if (hasVariantName) {
    // do something
  } else {
    // do something else
  }
  

  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"

await testTrack.logIn('myapp_user_id', '12345');
// From this point on you have existing split assignments from a previous device.

高级配置

当你打电话 load() 或者说 create() 您可以在分析对象和错误日志中选择通过。 例如:

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

测试

创建测试跟踪实例, 用于预配置任务测试, 没有网络请求 .

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 支持根据您的项目计划进行严格的类型检查 .

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<Schema>({
  /* ... */
});

// 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,用于配置测试音轨.

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。该文物包括所有依赖性,可以直接用于浏览器.

<script src="/path/to/index.iife.js"></script>
<script type="module">
  const testTrack = await TestTrack.load({
    client: {
      url: 'https://testtrack.example.com',
      appName: 'my_app',
      appVersion: '1.0.0',
      buildTimestamp: '2024-01-01T00:00:00Z'
    },
    storage: TestTrack.createCookieStorage({
      domain: '.example.com'
    })
  });
  // Use testTrack.vary(), testTrack.ab(), etc.
</script>

如何贡献

我们非常希望你能出力! 任何有利于大多数人的 test_track 鼓励用户——从文档修补到全新的功能.

在潜入之前, 检查我们的问题追踪器 并且考虑创建一个新问题,以便早日获得对您提议的修改的反馈.

二. 建议的工作流程

1. 将项目叉开,为您的贡献创建一个新的分支.
2. 填写您的贡献( 以及任何适用的测试范围) .
3. 确保所有测试通过.
4. 提交拉动请求 .

正在测试

1. 运行 pnpm install 下载依赖关系
2. 运行 pnpm test 运行测试
3. 运行 pnpm build 建造可分配物