Node.js SDK--A/B测试-火山引擎

文档中心

立即注册

导航

Node.js SDK

最近更新时间：2024.10.25 11:11:01首次发布时间：2024.10.17 20:06:50

下载SDK

您可以单击下载地址，进入Node.js SDK详情页面，在页面中可查看当前最新的SDK版本，并下载使用对应版本的SDK。

使用及说明

使用示例

以下以1.2.1版本为例，为您介绍Node.js SDK的使用说明。

import AbClient from "@datatester/node-sdk";
// const AbClient = require('@datatester/node-sdk').default

(async () => {
  // 在rangers应用管理中查询token信息
  const abClient = new AbClient("token");

  // 因为返回的是promise，业务使用上需要自行处理reject行为
  try {
    const conf = await abClient.activate(
      "key",
      "decisionId",
      "trackId",
      new Map(),
      ""
    );
    // 获取key版本配置
    const config = conf.val;
  } catch (e) {
    console.error(e);
  }
})();

初始化参数

名词	类型	说明
token	string	必填，app 级别的 token，即应用中的App Key，可以在DataTester控制台应用列表中查看。 SaaS-云原生 SaaS-非云原生
metaHost	string	获取 meta 数据服务 host，默认为 AbClient.metaHost.cn。说明私有化场景需手动按需修改。
trackHost	string	上报实验曝光数据，默认为 AbClient.trackHost.cn
interval	number	元数据更新间隔时间，单位秒，默认 60s
metaType	string	分流元数据的来源类型，可选值：'server'，'cdn', 'file' server：默认值，由DataTester提供的分流服务 'cdn', 'file'：如果需要使用自建的分流服务，可按需修改为对应类型配置成‘file’时，仅初始化时对文件读取一次，不会按照 interval 去更新数据
metaFilePath	string	metaType==='file'时候才生效，元数据文件本地路径，使用前确保应用对文件有可读权限
metaPath	string	metaType==='cdn'或‘server’时候才生效，默认值：/abmeta/v2/get_abtest_info 最终的上报地址通过metaHost+metaPath拼接而成，metaType为‘server’时可保持默认值，为‘cdn’时可按需修改。
enableFile	boolean	开启日志文件保存
dir	string	enableFile=true时，日志写入的文件路径，默认为当前应用启动的根路径，需确保应用对路径有写权限。
maxSize	string	日志文件最大值，配置示例。
level	string	需要记录的日志等级可选值：'console','info', 'warn', 'error'
formatter	function	对日志做自定义格式化输出，可配置参数请参照下载的Node.js SDK包中types/plugins/logger/index.d.ts文件，参考其中TLog相关参数。
trackMaxNum	number	一次上报的事件量个数，可选值 1-50，默认每 10 秒会自动上报一次，一次上报 50 条。
UserAbInfoHandler	object	命中数据（用户的标识ID数据、实验命中版本信息数据）的存储，如果您需要缓存这些数据到本地，以实现实验用户进组不出组的逻辑，需实现此对象，包含查询和保存两个方法： `{ query: (decisionId: string) => Promise<string>; createOrUpdate: (decisionId: string, flight2VersionStr: string) => Promise; }` decisionId：用户的标识ID，例如用户的uid。 flight2VersionStr：实验ID和版本ID的Map结构序列化后的字符串。

接口说明

接口类型参照nodejs代码中 types/type.d.ts文件。

接口列表

1. 动态调整获取元数据的间隔时间

接口示例：
```
setInterval(interval: number)
```
请求参数：参见下文的请求参数章节。
返回参数：void

2. 命中分流结果名称

接口示例：
```
setInterval(interval: number)
```
请求参数：参见下文的请求参数章节。
返回参数：Promise<string>

3. 命中分流结果名称并曝光实验信息

接口示例：

getExperimentVariantNameWithImpression(experimentId: string, decisionId: string, trackId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<string>

4. 命中分流结果配置信息

接口示例：

getExperimentConfigs(experimentId: string, decisionId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<TConfig>，详情请参见下文的返回值(TConfig)章节。

5. 命中分流结果配置信息并曝光信息

接口示例：

getExperimentConfigsWithImpression(experimentId: string, decisionId: string, trackId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<TConfig>，详情请参见下文的返回值(TConfig)章节。

6. 获取 app 下所有实验命中分流结果配置

接口示例：

getAllExperimentConfigs(decisionId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<TConfig>，详情请参见下文的返回值(TConfig)章节。

7. 检验 feature flag 是否命中

接口示例：

verifyFeatureEnabled(featureId: string, decisionId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<boolean>

8. feature flag 分流结果配置

接口示例：

getFeatureConfigs(featureId: string, decisionId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<TConfig>，详情请参见下文的返回值(TConfig)章节。

9. feature flag 分流结果配置并曝光信息

接口示例：

getFeatureConfigsWithImpression(featureId: string, decisionId: string, trackId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<TConfig>，详情请参见下文的返回值(TConfig)章节。

10. 命中的所有 feature flag 版本信息

接口示例：

getAllFeatureConfigs(decisionId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<TConfig>，详情请参见下文的返回值(TConfig)章节。

11. 获取所有命中的 feature flag id

接口示例：

getEnabledFeatureIds(decisionId: string, attributes: Map<string, any>, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<string[]>

12. 根据 key 做分流，并上报实验信息

接口示例：

activate(variantKey: string, decisionId: string, trackId: string, attributes: Map<string, any>, defaultValue: unkown, options?: TOptions)

请求参数：参见下文的请求参数章节。
返回参数：Promise<{val: any}>
返回逻辑：命中的实验信息 -> 命中的 feature flag 信息 -> 传入的默认值

13. 主动关闭所有元数据服务的 schedule job

接口示例：
```
close()
```
请求参数：参见下文的请求参数章节。
返回参数：void

请求入参

参数	类型	说明
interval	number	元数据获取时间间隔
experimentId	string	实验 id
decisionId	string	决策 ID, 分流口径，和系统中设置的白名单数据行为一致
featureId	string	feature flag id
trackId	string	上报数据唯一标识，事件上报用户标识，用于事件上报，请替换为客户的真实用户标识
attributes	Map<string, any>	用户自身的属性，用于和创建实验时设置的目标受众的用户属性做比对比

返回值(TConfig)

参数	类型	说明
val	string	元数据获取时间间隔
vid	string	实验版本 id
entity_id	string	决策 ID，分流口径

不同场景使用说明

自定义获取元数据和实验信息曝光地址

SaaS-云原生、SaaS-非云原生服务不同区域的配置

import AbClient from '@datatester/node-sdk'

// metaHost
// cn: AbClient.metaHost.cn
// sg: AbClient.metaHost.sg
// va: AbClient.metaHost.va

// trackHost
// cn: AbClient.trackHost.cn
// sg: AbClient.trackHost.sg
// va: AbClient.trackHost.va

const abSdk = new AbClient('token', {
    trackHost: AbClient.trackHost.sg
    metaHost: AbClient.metaHost.sg
})

私有化服务

import AbClient from '@datatester/node-sdk'
const abSdk = new AbClient('token', {
    trackHost: '' // 可访问到的上报http接口的host
    metaHost: ''// 可访问到的获取元数据http接口的host
})

监听内部日志

sdk 对外暴露了一个 EventEmitter 的实现，可以对 sdk 内部一些日志进行监听

// meta获取成功
abSdk.on("meta.success", (data) => {});
// meta获取失败
abSdk.on("meta.failure", (error) => {});
// ...

使用SDK进行分流

服务端项目工程中，本地调取分流代码示例如下：

const abClient = new AbClient("token")
const attrs = new Map()
attrs.set("key", "value")

const config = testerClient.activate("key", "decisionId", "trackId", attrs, {val: "defaultValue"})
const value = config.val
if (value === 'xx') {
   // 命中xx
} else if (value === 'yy') {
    // 命中yy
} else {
    // 兜底
}

// json类型
const jsonValue = JSON.parse(value)
if (jsonValue['key']) {
 // 
}