# @convertcom/js-sdk 中文文档

规范地址：https://npmcn.com/package/%40convertcom/js-sdk/

版本：5\.0\.2
npm 元数据更新时间：2026-09-17T14:35:11.945Z
中文译文更新时间：2026-11-10T17:31:19.400Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40convertcom/js-sdk
原文对照：https://npmcn.com/package/%40convertcom/js-sdk/?lang=original
项目主页：https://github.com/convertcom/javascript-sdk#readme
源码仓库：https://github.com/convertcom/javascript-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.7 MB，116 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=8\.0\.0
- 运行依赖：0 个
- peer 依赖：@convertcom/js-sdk-api \>=3\.0\.1，@convertcom/js-sdk-data \>=4\.0\.1，@convertcom/js-sdk-enums \>=3\.0\.1，@convertcom/js-sdk-event \>=3\.0\.1，@convertcom/js-sdk-rules \>=3\.0\.1，@convertcom/js-sdk-types \>=4\.0\.1，@convertcom/js-sdk-utils \>=3\.0\.1，@convertcom/js-sdk-logger \>=3\.0\.1，@convertcom/js-sdk-segments \>=3\.0\.1，@convertcom/js-sdk-bucketing \>=4\.0\.1，@convertcom/js-sdk-experience \>=3\.0\.1
- 首次发布：2023-04-09T16:52:35.753Z
- 最新版本发布：2026-09-17T14:35:11.587Z
- 近 30 天下载量：17741（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 8 个）

## 中文简介

* * *

## 安装

```sh
npm install @convertcom/js-sdk
```

也可以使用：`pnpm add @convertcom/js-sdk`、`yarn add @convertcom/js-sdk`、`bun add @convertcom/js-sdk`

## README

# 转换 Insights, Inc. JavaScript SDK

* * *

![coverage](https://convertcom.github.io/javascript-sdk/coverage.svg) [![license](https://img.shields.io/badge/license-Apache--2.0-green)](https://choosealicense.com/licenses/apache-2.0/)

* * *

## 目录

1.  [关于](https://npmcn.com/package/%40convertcom/js-sdk/#readme-about)
2.  [捐款](https://npmcn.com/package/%40convertcom/js-sdk/#readme-contributing)
3.  [文档](https://npmcn.com/package/%40convertcom/js-sdk/#readme-documentation)
4.  [所需资源](https://npmcn.com/package/%40convertcom/js-sdk/#readme-requirements)
    -   [常规](https://npmcn.com/package/%40convertcom/js-sdk/#readme-1-general)
    -   [观众](https://npmcn.com/package/%40convertcom/js-sdk/#readme-2-audiences)
    -   [部分](https://npmcn.com/package/%40convertcom/js-sdk/#readme-3-segments)
    -   [规则](https://npmcn.com/package/%40convertcom/js-sdk/#readme-4-rules)
    -   [经验](https://npmcn.com/package/%40convertcom/js-sdk/#readme-5-experiences)
    -   [特征](https://npmcn.com/package/%40convertcom/js-sdk/#readme-6-features)
    -   [环境](https://npmcn.com/package/%40convertcom/js-sdk/#readme-7-environments)
5.  [安装开始](https://npmcn.com/package/%40convertcom/js-sdk/#readme-getting-started-with-installation)
6.  [使用 SDK](https://npmcn.com/package/%40convertcom/js-sdk/#readme-using-the-sdk)
    -   [综合实例](https://npmcn.com/package/%40convertcom/js-sdk/#readme-comprehensive-examples)
    -   [导入 SDK 到您的工程](https://npmcn.com/package/%40convertcom/js-sdk/#readme-import-the-sdk-into-your-project)
    -   [使用 SDK 键初始化](https://npmcn.com/package/%40convertcom/js-sdk/#readme-initialize-using-the-sdk-key)
    -   [使用静态配置初始化](https://npmcn.com/package/%40convertcom/js-sdk/#readme-initialize-using-static-configuration)
    -   [SDK 配置选项](https://npmcn.com/package/%40convertcom/js-sdk/#readme-sdk-configuration-options)
    -   [创建用户背景](https://npmcn.com/package/%40convertcom/js-sdk/#readme-create-user-context)
7.  [SDK 经验运行方法](https://npmcn.com/package/%40convertcom/js-sdk/#readme-sdk-methods-for-running-experiences)
    -   [一般性考虑](https://npmcn.com/package/%40convertcom/js-sdk/#readme-general-considerations)
    -   [运行全部活动体验](https://npmcn.com/package/%40convertcom/js-sdk/#readme-run-all-active-experiences)
    -   [运行单个体验](https://npmcn.com/package/%40convertcom/js-sdk/#readme-run-a-single-experience)
    -   [运行多功能](https://npmcn.com/package/%40convertcom/js-sdk/#readme-run-multiple-features)
    -   [运行单一特性](https://npmcn.com/package/%40convertcom/js-sdk/#readme-run-a-single-feature)
    -   [音轨转换事件](https://npmcn.com/package/%40convertcom/js-sdk/#readme-track-conversion-events)
    -   [运行自定义片段](https://npmcn.com/package/%40convertcom/js-sdk/#readme-run-custom-segments)
    -   [设置默认部分](https://npmcn.com/package/%40convertcom/js-sdk/#readme-set-default-segments)
    -   [更新访问者属性](https://npmcn.com/package/%40convertcom/js-sdk/#readme-update-visitor-properties)
    -   [获取配置实体](https://npmcn.com/package/%40convertcom/js-sdk/#readme-get-config-entity)
    -   [由 Id 获取配置实体](https://npmcn.com/package/%40convertcom/js-sdk/#readme-get-config-entity-by-id)
    -   [释放待排队列](https://npmcn.com/package/%40convertcom/js-sdk/#readme-release-pending-queues)
8.  [活动](https://npmcn.com/package/%40convertcom/js-sdk/#readme-events)
9.  [提供持久数据系统](https://npmcn.com/package/%40convertcom/js-sdk/#readme-provide-persistent-datastore)
10.  [常见错误和解决问题](https://npmcn.com/package/%40convertcom/js-sdk/#readme-common-errors-and-troubleshooting)
11.  [构建环境变量](https://npmcn.com/package/%40convertcom/js-sdk/#readme-build-environment-variables)
12.  [自定义构建](https://npmcn.com/package/%40convertcom/js-sdk/#readme-custom-build)
13.  [结论](https://npmcn.com/package/%40convertcom/js-sdk/#readme-conclusion)
14.  [贷项](https://npmcn.com/package/%40convertcom/js-sdk/#readme-credits)

* * *

## 关于

此寄存器包含 **JavaScript SDK(节点和浏览器)** 需要整合转换。 连锁店 **Fullstack 产品(特征测试、特征旗帜、特征推出)** 进入第三方应用程序。 它由Conversion.com团队维护.

* * *

## 捐款

见 [捐款](https://npmcn.com/package/%40convertcom/js-sdk/CONTRIBUTING.md) 详细介绍如何提交捐款.

* * *

## 文档

参见 [JavaScript SDK 文档](https://convertcom.github.io/javascript-sdk/) 关于SDK模块和实用辅导的细节.

* * *

## 所需资源

Fullstack项目与网络项目略有不同. 以下是一些要点:

### 1\. 概况

所有实体都必须有一个独特的标识符 `key` 这是 `string` 当在网络界面中定义时.

### 2\. 听众

SDK不直接管理持久性. 取而代之的是,您可以提供自己的DataStore,以使用户桶持续使用. Fullstack项目中所有创建的受众都应该是类型 `transient`,在每次遇到经验时检查条件.

### 3\. 部分

片段代表类型对象 `segmentation`。每个页面视图检查条件,直到满足。 在Fullstack项目中,片段不会持续,除非您使用自己的DataStore.

### 4\. 规则

规则限于下列类型:

1.  `generic_bool_key_value`:匹配类型选择仅限于 `equals`。 。 。 .
2.  `generic_numeric_key_value`:匹配类型选择仅限于 `equalsNumber`, (中文(简体) ), `less`,以及 `lessEqual`。 。 。 .
3.  `generic_text_key_value`:匹配类型选择仅限于 `matches`, (中文(简体) ), `regexMatches`, (中文(简体) ), `contains`, (中文(简体) ), `endsWith`,以及 `startsWith`。 。 。 .

> **说明:** 每个规则必须有一个独特的标识符 `key` 这是 `string`。 。 。 .

### 5\. 经验

经验仅限于以下类型:

1.  `a/b_fullstack`页:1 `a/b` 经历.
2.  `feature_rollout`:只有一种变化并非原生的体验.

### 6\. 特征

> 仅供Furstack项目使用.

地物是可以在网络界面中定义并被SDK使用的变量,支持以下类型: 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地物 地 地 地 地 地 地 地 地 地 为地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地 地

1.  `boolean`
2.  `integer`
3.  `string`
4.  `json`

### 7\. 环境

> 仅供Furstack项目使用.

所有匹配规则仅适用于同一范围内的实体 `environment`。您可以创建尽可能多的环境。 默认环境为:

1.  `staging`
2.  `production`

* * *

## 安装开始

使用模块安装 `npm` 或者说 `yarn`数字 :

```bash
npm install --save @convertcom/js-sdk
```

软件包的构建包含以不同格式生成切入点的定义:

-   普通JS( 常规JS )`CJS`) - 发现于 `lib/index.js` 或者说 `lib/index.min.js` 用于修改版本.
-   ES 模块`ESM`) - 发现于 `lib/index.mjs` 或者说 `lib/index.min.mjs` 用于修改版本.
-   通用模块定义`UMD`) - 发现于 `lib/index.umd.js` 或者说 `lib/index.umd.min.js` 用于修改版本.

您也可以通过上述入口加载 [(单位:公斤)](https://unpkg.com/)。这种方法增加了对第三方URL的依赖性,并且只推荐用于评价目的:

```html
<script src="https://unpkg.com/@convertcom/js-sdk/lib/index.js"></script>

<!-- or the minified version -->
<script src="https://unpkg.com/@convertcom/js-sdk/lib/index.min.js"></script>
```

* * *

## 使用 SDK

### 综合实例

#### 简单的节点JS演示视频

#### 详细的基于 JS 的教学

更详细的辅导和指南请访问以下链接:

-   [测试转换事件](https://convertcom.github.io/javascript-sdk/tutorial-test-conversion.html)
-   [测试特性标记](https://convertcom.github.io/javascript-sdk/tutorial-test-features.html)
-   [测试用户段](https://convertcom.github.io/javascript-sdk/tutorial-test-segments.html)
-   [测试变化](https://convertcom.github.io/javascript-sdk/tutorial-test-variations.html)

### 导入 SDK 到您的工程

**ES6号:**

支助 `import` 财务报告和审定财务报表 `export` 现代前端框架(如React,Vue,Angular等)中的语句.

> 必须转换到客户端浏览器中工作 .

```typescript
import ConvertSDK from '@convertcom/js-sdk';
```

**无害环境管理:**

支助 `import` 财务报告和审定财务报表 `export` eS模块软件包中的语句(类型) `module` 内 `package.json`) (中文(简体) ).

> 必须转换到客户端浏览器中工作 .

```typescript
import ConvertSDKModule from '@convertcom/js-sdk';
const ConvertSDK = (ConvertSDKModule as any).default;
```

**常见JS :**

支助 `require` 财务报告和审定财务报表 `exports` 在节点环境中.

> 必须转换到客户端浏览器中工作 .

```typescript
const {default: ConvertSDK} = require('@convertcom/js-sdk');
```

**UMD: (英语)**

> 直接在客户端浏览器中工作.

```html
<script src="https://unpkg.com/@convertcom/js-sdk/lib/index.umd.min.js"></script>
```

```typescript
const {default: ConvertSDK} = window.ConvertSDK; // ConvertSDK is provided by https://unpkg.com/@convertcom/js-sdk/lib/index.umd.min.js
```

SDK实例可通过提供一种 `sdkKey` 或整个项目的数据对象.

#### 使用 SDK 键初始化

包含 `sdkKey` 作为选项中的字符串属性,您将对象传递到构造实例。 SDK 将从 Transform 的 CDN 获取工程配置, 然后每次刷新 `dataRefreshInterval` 毫秒长.

> 注:如果使用经认证的密钥,则需要包含 `sdkKeySecret` 作为字符串属性.

```typescript
import type {ConvertInterface, ConvertConfig} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const convertSDK: ConvertInterface = new ConvertSDK({
  sdkKey: 'xxx',
  sdkKeySecret: 'xxx', // required when using an authenticated SDK key
  dataRefreshInterval: 300000, // in milliseconds (5 minutes)
  environment: 'staging' // can also be "live"; this is configured in the Convert UI.
} as ConvertConfig);
convertSDK.onReady().then(() => {
  // console.log('SDK Data:', convertSDK.data);
  // create user context
  // run experience(s)
  // ...
});
```

之后,SDK成功即时化,项目配置数据被下载,并准备用于启动用户Context.

#### 使用静态配置初始化

或者,不提供 `sdkKey`,可以提供静态工程配置。 项目配置数据可以从 _[https://cdn-4.convertexerments.com/api/v1/config/account id/project id (中文(中国大陆) )](https://cdn-4.convertexperiments.com/api/v1/config/account_id/project_id_)。 。 。 ._

```typescript
import type {ConvertInterface, ConvertConfig} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const projectConfig = {
  // your static project configuration data
};

const convertSDK: ConvertInterface = new ConvertSDK({
  projectConfig,
  environment: 'staging' // can also be "live"; this is configured in the Convert UI.
} as ConvertConfig);
convertSDK.onReady().then(() => {
  // create user context
  // run experience(s)
});
```

在使用静态项目数据时,SDK一创建实例就被即时使用,并可以立刻用于启动用户Context.

### SDK 配置选项

以下显示配置选项的对象模型 :

```typescript
import {LogLevel} from '@convertcom/js-sdk';

const config = {
  sdkKey: '', // either this or 'data' has to be provided
  sdkKeySecret: '', // required when using an authenticated SDK key
  environment: 'staging',
  logger: {
    logLevel: LogLevel.DEBUG,
    customLoggers: [] // Allows 3rd party loggers to be passed
  },
  bucketing: {
    hash_seed: 9999, // murmurhash seed
    max_traffic: 10000, // max hash (representing 100% traffic allocation)
    excludeExperienceIdHash: false // whether to ignore prefixing the generated hash with the experience id
  },
  dataStore: null, // Allows 3rd party data store to be passed (optional)
  dataRefreshInterval: 300000, // in milliseconds (5 minutes)
  data: projectData,
  events: {
    batch_size: 10, // max network requests to be released per call
    release_interval: 10000 // time in milliseconds between network releasing queue (including the initial release)
  },
  network: {
    tracking: true, // can be set to false to disable tracking events
    cacheLevel: 'default', // can be set to 'low' for short-lived cache (for development purposes only)
    source: 'js-sdk' // string identifier indicating the source of network requests
  }
};
```

这个 `projectData` 结构描述于 [https://api.convert.com/doc/ service/#tag/Project-Config 互联网档案馆的存檔,存档日期2013-12-02](https://api.convert.com/doc/serving/#tag/Project-Config)。 。 。 .

### 创建用户背景

一旦SDK创建并被即时化,下一步就是在范围上为用户创造一个独特的上下文.

创建 UserContext 时, 独一无二 `userId` 需要时间。 这将用来决定呈现的变异/特点。 只要这样 `userId` 对用户来说,不会改变,经验配置保持不变(变化不增加或删除,流量分配不变),特性/变化桶将保持不变。 否则,你看 [提供持久数据系统](https://npmcn.com/package/%40convertcom/js-sdk/#readme-provide-persistent-datastore)。 。 。 .

为方便起见,列出 **用户属性** 在创建用户Context时,可以提供日后在受众定义内使用的评价. 当调用SDK功能操作方法进行运行时,任何这些操作都可以通过再次提供它们来改变 `attributes.visitorProperties` 在设置值时 `attributes.updateVisitorProperties` 改为 `true`。 。 。 .

```typescript
import type {ContextInterface} from '@convertcom/js-sdk';

const userContext: ContextInterface = convertSDK.createContext(
  'user-unique-id',
  {
    country: 'US',
    language: 'en'
  }
);
```

创建后 `userContext`,运行经验的方法可以称为:

```typescript
import type {BucketedVariation} from '@convertcom/js-sdk';

const variation: BucketedVariation =
  userContext.runExperience('experience-key');
```

* * *

## SDK 经验运行方法

### 一般性考虑

每一个方法 `userContext` 运行一个或多个体验的曝光可以接收一个有两把键的对象:

-   `locationProperties` - 包含用于评估经验所在位置的属性的关键值对象.
-   `visitorProperties` - 包含用于评价经验受众的属性的按键值对象,该对象将覆盖创建时提供的相同的按键 `userContext`。 。 。 .

此外 `environment` 可作为第三个参数提供.

### 运行全部活动体验

这种方法将每个活动经验循环,运行,并返回每个经验的选定变量. 它根据配置规则(位置和受众)决定用户是否应该被打入所有变体.

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 属性 | 对象 | 没有 | 为用户指定属性的对象 . |
|  |  |  | `locationProperties`:用于位置匹配的密钥值对对象. |
|  |  |  | `visitorProperties`:用于瞄准观众的密钥值对对象. |
|  |  |  | `updateVisitorProperties`: 可选布尔来更新记忆中的访客属性. |
|  |  |  | `enableTracking`: 可选布尔来控制是否立即跟踪打桶事件(_默认为 `true`_) (中文(简体) ). |
|  |  |  | `environment`:可选字符串. |

#### 回返

桶状变体列表.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface,
  BucketedVariation
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const variations: BucketedVariation[] = context.runExperiences();
  console.log(variations);
});
```

### 运行单个体验

决定用户是否应该被打入一个单一的变体,该变体被映射到经验的独特钥匙上。 决定是根据所配置的经验规则作出的.

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 体验键 | 字符串 | 对 | 经验的关键应该被激活. |
| 属性 | 对象 | 没有 | 为用户指定属性的对象 . |
|  |  |  | `locationProperties`:用于位置匹配的密钥值对对象. |
|  |  |  | `visitorProperties`:用于瞄准观众的密钥值对对象. |
|  |  |  | `updateVisitorProperties`: 可选布尔来更新记忆中的访客属性. |
|  |  |  | `enableTracking`: 可选布尔来控制是否立即跟踪打桶事件(_默认为 `true`_) (中文(简体) ). |
|  |  |  | `environment`:可选字符串. |

#### 回返

白斑变异.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface,
  BucketedVariation
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const variation: BucketedVariation = context.runExperience('experience-key');
  console.log(variation);
});
```

### 运行多功能

获取用户已被桶装的特性列表 .

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 属性 | 对象 | 没有 | 为用户指定属性的对象 . |
|  |  |  | `locationProperties`:用于位置匹配的密钥值对对象. |
|  |  |  | `visitorProperties`:用于瞄准观众的密钥值对对象. |
|  |  |  | `updateVisitorProperties`: 可选布尔来更新记忆中的访客属性. |
|  |  |  | `environment`:可选字符串. |
|  |  |  | `typeCasting`:可选布尔来控制自动类型转换为变量所定义的类型. 默认为 `true`。 。 。 . |

#### 回返

桶状特征列表.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface,
  BucketedFeature
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const features: BucketedFeature[] = context.runFeatures();
  console.log(features);
});
```

### 运行单一特性

获取用户已经被桶装的单一特性, 映射到一个特性的独特密钥 .

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 特性键 | 字符串 | 对 | 一个特性键. |
| 属性 | 对象 | 没有 | 为用户指定属性的对象 . |
|  |  |  | `locationProperties`:用于位置匹配的密钥值对对象. |
|  |  |  | `visitorProperties`:用于瞄准观众的密钥值对对象. |
|  |  |  | `updateVisitorProperties`: 可选布尔来更新记忆中的访客属性. |
|  |  |  | `environment`:可选字符串. |
|  |  |  | `typeCasting`:可选布尔来控制自动类型转换为变量所定义的类型. 默认为 `true`。 。 。 . |
|  |  |  | `experienceKeys`: 可选的字符串组只使用指定的经验 . |

#### 回返

破烂特写.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface,
  BucketedFeature
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const feature: BucketedFeature = context.runFeature('feature-key');
  console.log(feature);
});
```

### 音轨转换事件

决定是否发送转换事件, 被映射到目标的独特密钥上 。 决定是根据配置的打入球规则作出的.

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 目标键 | 字符串 | 对 | 目标关键 |
| 属性 | 对象 | 没有 | 指定用户属性的对象。 接受2个属性 : |
|  |  |  | `ruleData` 用于目标匹配的按键对对象. |
|  |  |  | `conversionData` 用于交易数据的密钥值对。 每对接受3个属性: |
|  |  |  | 1\. 联合国. `amount` 数字表示顺序值. |
|  |  |  | 2\. 联合国. `productsCount` a 表示订单数量. |
|  |  |  | 3个. `transactionId` 一个独有的编号或字符串代表已支付的交易. |
|  |  |  | `conversionSetting` 用于跟踪设置的密钥值对对象: |
|  |  |  | 1\. 联合国. `forceMultipleTransactions` a布尔决定是否为同一访客积累收入. |

#### 回返

V.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  context.trackConversion('goal-key', {
    ruleData: {
      action: 'buy'
    },
    conversionData: [
      {
        key: 'amount',
        value: 10.3
      },
      {
        key: 'productsCount',
        value: 2
      },
      {
        key: 'transactionId',
        value: 'transaction-unique-id'
      }
    ],
    conversionSetting: {
      forceMultipleTransactions: false
    }
  });
});
```

### 运行自定义片段

决定是否在用户背景中更新自定义片段, 映射到片段的独特密钥 。 该决定是根据配置的分区规则作出的.

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 块键 | 数组 | 对 | 段键列表 . |
| 访问者 | 对象 | 没有 | 用于区段匹配的密钥值对对象. |

#### 回返

V.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  context.runCustomSegments(['segment-key'], {
    enabled: true
  });
});
```

### 设置默认部分

长期更新来访部分以供报告。 转换报告只包含以下属性: `browser`, (中文(简体) ), `devices`, (中文(简体) ), `source`, (中文(简体) ), `campaign`, (中文(简体) ), `visitorType`,以及 `country`。 。 。 .

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 部分 | 对象 | 对 | 键值对对象与初始对象合并 **用户属性** 创建于 [上下文](https://npmcn.com/package/%40convertcom/js-sdk/#readme-create-user-context)。 。 。 . |

#### 回返

V.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  context.setDefaultSegments({
    country: 'US'
  });
});
```

### 更新访问者属性

永久更新所有观众定义评价中使用的访客属性.

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 访客 | 字符串 | 对 | 用户独有的ID. |
| 访问者 | 对象 | 对 | 键值对对象与初始对象合并 **用户属性** 创建于 [上下文](https://npmcn.com/package/%40convertcom/js-sdk/#readme-create-user-context)。 。 。 . |

#### 回返

V.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  context.updateVisitorProperties({
    weather: 'rainy'
  });
});
```

### 获取配置实体

在配置中查找单个实体 `key`。 。 。 .

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 键 | 字符串 | 对 | 配置中发现的实体密钥 . |
| 实体类型 | 实体类型 | 对 | 配置实体之一: `EntityType.AUDIENCE`, (中文(简体) ), `EntityType.LOCATION`, (中文(简体) ), `EntityType.SEGMENT`, (中文(简体) ), `EntityType.FEATURE`, (中文(简体) ), `EntityType.GOAL`, (中文(简体) ), `EntityType.EXPERIENCE`,以及 `EntityType.VARIATION`。 。 。 . |

#### 回返

V.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface,
  Experience
} from '@convertcom/js-sdk';
import ConvertSDK, {EntityType} from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const exprience: Experience = context.getConfigEntity(
    'experience-key',
    EntityType.EXPERIENCE
  );
});
```

### 由 Id 获取配置实体

在配置中查找单个实体 `id`。 。 。 .

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 编号 | 编号 | 对 | 在配置中发现的实体 id . |
| 实体类型 | 实体类型 | 对 | 配置实体之一: `EntityType.AUDIENCE`, (中文(简体) ), `EntityType.LOCATION`, (中文(简体) ), `EntityType.SEGMENT`, (中文(简体) ), `EntityType.FEATURE`, (中文(简体) ), `EntityType.GOAL`, (中文(简体) ), `EntityType.EXPERIENCE`,以及 `EntityType.VARIATION`。 。 。 . |

#### 回返

V.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface,
  BucketedVariation,
  Feature,
  VariationChange
} from '@convertcom/js-sdk';
import ConvertSDK, {EntityType, VariationChangeType} from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const variation: BucketedVariation = context.runExperience('experience-key');
  const changesData: VariationChange = variation.changes.find(
    ({type}) => type === VariationChangeType.FULLSTACK_FEATURE
  );
  const feature: Feature = context.getConfigEntityById(
    changesData.data.feature_id,
    EntityType.FEATURE
  );
});
```

### 释放待排队列

将所有待定的 API/ DataStore 队列发送到服务器 .

#### 参数

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 原因 | 字符串 | 没有 | 用于调试目的自定义消息 . |

#### 回返

V.

#### 示例

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface,
  BucketedVariation
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

const convertSDK: ConvertInterface = new ConvertSDK(config);
convertSDK.onReady().then(() => {
  const context: ContextInterface = convertSDK.createContext('user-unique-id');
  const variations: BucketedVariation[] = context.runExperiences();

  // manually release all pending queue at some point later, like on click, component unmount
  context.releaseQueues().then(() => {
    console.log('all pending queue has been released');
  });
});
```

### 活动

您也可以捕捉 SDK 事件:

| 活动 | 触发由 | 回调数据 |
| --- | --- | --- |
| `ready` | 初始化 SDK | 无效 |
| `bucketing` | 运行经验 | {访客: `string`,体验关键: `string`,变量键 : `string` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 |
|  | 运行中的特性 | {访客: `string`,体验关键: `string`,功能键 : `string`状态 : `string` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 |
| `conversion` | 跟踪转换 | {访客: `string`,进球键: `string` {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}你觉得呢 |
| `location.activated` | 位置规则匹配 | {访客: `string`,位置:{d: `string`,名称: `string`键 : `string` {\\fn华文仿宋\\fs16\\1cHD1D1D1}我.. |
| `location.deactivated` | 位置规则不匹配( 仅在较早启用时) | {访客: `string`,位置:{d: `string`,名称: `string`键 : `string` {\\fn华文仿宋\\fs16\\1cHD1D1D1}我.. |
| `config.updated` | 刷新配置 | 无效 |

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface,
  Experience,
  Variation
} from '@convertcom/js-sdk';
import ConvertSDK, {EntityType, SystemEvents} from '@convertcom/js-sdk';

const convertSDK: ConvertInterface = new ConvertSDK({
  sdkKey: 'xxx'
} as ConvertConfig);

convertSDK.on(SystemEvents.READY, function (res, err) {
  if (err) {
    console.error(err);
  }
});

convertSDK.on(
  SystemEvents.BUCKETING,
  function ({visitorId, experienceKey, variationKey, featureKey, status}, err) {
    if (err) {
      console.error(err);
    } else {
      console.log(visitorId, experienceKey, variationKey, featureKey, status);
      // Example GA integrations can be done here
      // Note that you need to create audiences manually on the GA side
      const experienceName: Experience = context.getConfigEntity(
        experienceKey,
        EntityType.EXPERIENCE
      ).name;
      const variationName: Variation = context.getConfigEntity(
        variationKey,
        EntityType.VARIATION
      ).name;
      gtag('event', 'YOUR_GA_CUSTOM_EVENT', {
        experienceName,
        variationName
      });
    }
  }
);

convertSDK.on(SystemEvents.CONVERSION, function ({visitorId, goalKey}, err) {
  if (err) {
    console.error(err);
  } else {
    console.log(visitorId, goalKey);
  }
});

convertSDK.on(SystemEvents.CONFIG_UPDATED, function (res, err) {
  if (err) {
    console.error(err);
  }
});
```

### 提供持久数据系统

> **说明:** 此特性可选.

您可以提供自己的DataStore,使用户桶持续,确保一致的经验变化选择,无论经验配置的变化如何. 只要经验变化和流量分配不改变,最初的用户桶仍持续使用. 这个 [MurmurHash 算法](https://en.wikipedia.org/wiki/MurmurHash) 用于决定选择哪些变化,以确保一致性.

提供的DataStore接口预计将有两种方法: `set` 财务报告和审定财务报表 `get`。 。 。 .

```typescript
import type {
  ConvertInterface,
  ConvertConfig,
  ContextInterface
} from '@convertcom/js-sdk';
import ConvertSDK from '@convertcom/js-sdk';

const config: ConvertConfig = {
  // full configuration options
};

class CustomDataStore {
  #data = {};

  get(key) {
    if (!key) return this.#data;
    return this.#data[key.toString()];
  }

  set(key, value) {
    if (!key) throw new Error('Invalid CustomDataStore key!');
    this.#data[key.toString()] = value;
  }
}

const dataStore = new CustomDataStore();
const convertSDK: ConvertInterface = new ConvertSDK({
  ...config,
  dataStore
} as ConvertConfig);
```

### 常见错误和解决问题

#### 错误: SDK 初始化失败

-   **原因 :** 错误 `sdkKey` 网络问题.
-   **解决方案 :** 校验 `sdkKey` 并确保网络连接.

#### 错误: 用户上下文创建失败

-   **原因 :** 失踪或无效 `userId`。 。 。 .
-   **解决方案 :** 确保有效 `userId` 在创建上下文时提供.

#### 错误: 找不到经验

-   **原因 :** 错误 `experienceKey` 或项目中未界定的经验.
-   **解决方案 :** 校验 `experienceKey` 并确保在项目中正确配置经验.

#### 错误: 特性未找到

-   **原因 :** 错误 `featureKey` 或项目中未定义的特性.
-   **解决方案 :** 校验 `featureKey` 并确保在项目中正确配置该特性.

* * *

## 构建环境变量

| 环境变量 | 说明 | 数值 |
| --- | --- | --- |
| `LOG_LEVEL` | 指定要保存的日志语句级别,同时从捆绑输出中去除其余内容. | `0` {\\FN方正粗倩简体\\FS12\\AN8\\1CHFFFF00\\B0}所有, `1` = DEBUG, (英语), `2` = INFO,(原始内容存档于2008年), `3` 战火, `4` 错误, `5` 安静 |
| `BUNDLES` | 逗号分隔符,用于指定要构建的捆绑 。 默认包含全部捆绑 . | `cjs`, (中文(简体) ), `cjs-legacy`, (中文(简体) ), `esm`, (中文(简体) ), `umd` |

* * *

## 自定义构建

在某些情况下,您可以使用定制的建筑。 例如:

1.  要减少捆绑大小并删除所有日志语句 : `LOG_LEVEL=5 yarn sdk:build`
2.  只构建 CommunityJS 捆绑 : `BUNDLES=cjs,cjs-legacy yarn sdk:build`

此外,您甚至可以将这个寄存器作为您自己的一部分 `TypeScript` 项目:

1.  将转换 JavaScript SDK 寄存器添加到您自己的子模块中 :
    
    ```bash
    git submodule add https://github.com/convertcom/javascript-sdk javascript-sdk
    ```
    
2.  选择以下方法之一:
    
    -   **工作空间**: 增加以下内容: `workspaces` 给您的 `package.json` (单位:千美元)_假设子模块位于您的仓库根下_:
        
        ```json
        {
          "workspaces": ["javascript-sdk/packages/*"]
        }
        ```
        
        如果使用 PnP, 请添加以下内容: `packages` 给您的 `pnpm-workspace.yaml` 相反:
        
        ```yaml
        packages:
          - 'javascript-sdk/packages/*'
        ```
        
    -   **编译器选项**: 增加以下内容: `paths` 下级 `compilerOptions` 您的电话 `tsconfig.json` (欲了解更多信息,请参考 [类型脚本文档](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html):
        
        ```json
        {
          "compilerOptions": {
            "paths": {
              "@convertcom/js-sdk-api": ["./javascript-sdk/packages/api"],
              "@convertcom/js-sdk-bucketing": [
                "./javascript-sdk/packages/bucketing"
              ],
              "@convertcom/js-sdk-data": ["./javascript-sdk/packages/data"],
              "@convertcom/js-sdk-enums": ["./javascript-sdk/packages/enums"],
              "@convertcom/js-sdk-event": ["./javascript-sdk/packages/event"],
              "@convertcom/js-sdk-experience": [
                "./javascript-sdk/packages/experience"
              ],
              "@convertcom/js-sdk-logger": ["./javascript-sdk/packages/logger"],
              "@convertcom/js-sdk-rules": ["./javascript-sdk/packages/rules"],
              "@convertcom/js-sdk-segments": [
                "./javascript-sdk/packages/segments"
              ],
              "@convertcom/js-sdk-types": ["./javascript-sdk/packages/types"],
              "@convertcom/js-sdk-utils": ["./javascript-sdk/packages/utils"],
              "@convertcom/js-sdk": ["./javascript-sdk/packages/js-sdk"]
            }
          }
        }
        ```
        
3.  将以下脚本添加到您的 `package.json`数字 :
    
    ```json
    {
      "scripts": {
        "build:sdk": "cd javascript-sdk && BUNDLES=cjs,esm LOG_LEVEL=5 yarn sdk:build"
      }
    }
    ```
    
    > 注意两者 `BUNDLES` 财务报告和审定财务报表 `LOG_LEVEL` 可选( e)_见 [构建环境变量](https://npmcn.com/package/%40convertcom/js-sdk/#readme-build-environment-variables) 上文_(中文(简体) )
    
4.  现在您可以同时构建 JavaScript SDK 工程(_假设您使用 `rollup` 用于捆绑_:
    
    ```json
    {
      "scripts": {
        "build": "yarn build:sdk && rollup -c"
      }
    }
    ```
    
5.  你得跑开 `yarn` 在子模块内 `javascript-sdk` 还:
    
    ```bash
    # Update ConvertSDK submodule
    git submodule update --init --remote
    # Install your project dependencies as per your `package.json`
    yarn
    # Install ConvertSDK dependencies
    cd javascript-sdk && yarn
    # Build your project
    yarn build
    ```
    

* * *

## 结论

该文件为如何在您的项目中集成和使用转换透视(Conversion Insights, Inc. JavaScript SDK)提供了全面的指南. 它包括从安装和配置到高级使用和排除故障的所有必要措施.

如果您遇到任何问题或有问题,请随意联系Orvery.com支援小组或打开一个问题 [GitHub 仓库](https://github.com/convertcom/javascript-sdk)。 。 。 .

皈依快乐!

* * *

## 贷项

版权所有:"2024转换透视"股份有限公司.

## 常见问题

### 如何安装 @convertcom/js-sdk？

在项目目录运行 npm install @convertcom/js-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@convertcom/js-sdk-api（\>=3\.0\.1）、@convertcom/js-sdk-data（\>=4\.0\.1）、@convertcom/js-sdk-enums（\>=3\.0\.1）、@convertcom/js-sdk-event（\>=3\.0\.1）、@convertcom/js-sdk-rules（\>=3\.0\.1）、@convertcom/js-sdk-types（\>=4\.0\.1）、@convertcom/js-sdk-utils（\>=3\.0\.1）、@convertcom/js-sdk-logger（\>=3\.0\.1）、@convertcom/js-sdk-segments（\>=3\.0\.1）、@convertcom/js-sdk-bucketing（\>=4\.0\.1）、@convertcom/js-sdk-experience（\>=3\.0\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @convertcom/js-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @convertcom/js-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @convertcom/js-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=8\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @convertcom/js-sdk 可以商用吗？

@convertcom/js-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convertcom/js-sdk 的下载量有多少？

根据 npm 官方下载统计，@convertcom/js-sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 17,741 次，日均约 591 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @convertcom/js-sdk 还在维护吗？

最新版本 5\.0\.2 发布于 2026/09/17（1 个月前）；至今共发布 38 个版本，其中过去 12 个月发布了 8 个；首次发布于 2023/04/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。