@convertcom/js-sdk

中文文档
5.0.2发布于 2026/09/17Apache-2.0TypeScriptESM + CJS零依赖构建来源已验证近 30 天下载 1.8万

中文使用文档
文档目录38 节
  1. 目录
  2. 关于
  3. 捐款
  4. 文档
  5. 所需资源
  6. 1. 概况
  7. 2. 听众
  8. 3. 部分
  9. 4. 规则
  10. 5. 经验
  11. 6. 特征
  12. 7. 环境
  13. 安装开始
  14. 使用 SDK
  15. 综合实例
  16. 导入 SDK 到您的工程
  17. SDK 配置选项
  18. 创建用户背景
  19. SDK 经验运行方法
  20. 一般性考虑
  21. 运行全部活动体验
  22. 运行单个体验
  23. 运行多功能
  24. 运行单一特性
  25. 音轨转换事件
  26. 运行自定义片段
  27. 设置默认部分
  28. 更新访问者属性
  29. 获取配置实体
  30. 由 Id 获取配置实体
  31. 释放待排队列
  32. 活动
  33. 提供持久数据系统
  34. 常见错误和解决问题
  35. 构建环境变量
  36. 自定义构建
  37. 结论
  38. 贷项

转换 Insights, Inc. JavaScript SDK


coverage license


目录

  1. 关于
  2. 捐款
  3. 文档
  4. 所需资源
  5. 安装开始
  6. 使用 SDK
  7. SDK 经验运行方法
  8. 活动
  9. 提供持久数据系统
  10. 常见错误和解决问题
  11. 构建环境变量
  12. 自定义构建
  13. 结论
  14. 贷项

关于

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


捐款

见 捐款 详细介绍如何提交捐款.


文档

参见 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数字 :

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 用于修改版本.

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

<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 的教学

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

导入 SDK 到您的工程

ES6号:

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

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

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

无害环境管理:

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

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

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

常见JS :

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

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

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

UMD: (英语)

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

<script src="https://unpkg.com/@convertcom/js-sdk/lib/index.umd.min.js"></script>
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 作为字符串属性.

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 (中文(中国大陆) )。 。 。 .

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 配置选项

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

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

创建用户背景

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

创建 UserContext 时, 独一无二 userId 需要时间。 这将用来决定呈现的变异/特点。 只要这样 userId 对用户来说,不会改变,经验配置保持不变(变化不增加或删除,流量分配不变),特性/变化桶将保持不变。 否则,你看 提供持久数据系统。 。 。 .

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

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

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

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

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:可选字符串.

回返

桶状变体列表.

示例

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:可选字符串.

回返

白斑变异.

示例

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

回返

桶状特征列表.

示例

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: 可选的字符串组只使用指定的经验 .

回返

破烂特写.

示例

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.

示例

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.

示例

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

参数

参数类型需求说明
部分对象对键值对对象与初始对象合并 用户属性 创建于 上下文。 。 。 .

回返

V.

示例

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.
访问者对象对键值对对象与初始对象合并 用户属性 创建于 上下文。 。 。 .

回返

V.

示例

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.

示例

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.

示例

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.

示例

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刷新配置无效
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 算法 用于决定选择哪些变化,以确保一致性.

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

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 寄存器添加到您自己的子模块中 :

    git submodule add https://github.com/convertcom/javascript-sdk javascript-sdk
    
  2. 选择以下方法之一:

    • 工作空间: 增加以下内容: workspaces 给您的 package.json (单位:千美元)假设子模块位于您的仓库根下:

      {
        "workspaces": ["javascript-sdk/packages/*"]
      }
      

      如果使用 PnP, 请添加以下内容: packages 给您的 pnpm-workspace.yaml 相反:

      packages:
        - 'javascript-sdk/packages/*'
      
    • 编译器选项: 增加以下内容: paths 下级 compilerOptions 您的电话 tsconfig.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数字 :

    {
      "scripts": {
        "build:sdk": "cd javascript-sdk && BUNDLES=cjs,esm LOG_LEVEL=5 yarn sdk:build"
      }
    }
    

    注意两者 BUNDLES 财务报告和审定财务报表 LOG_LEVEL 可选( e)见 构建环境变量 上文(中文(简体) )

  4. 现在您可以同时构建 JavaScript SDK 工程(假设您使用 rollup 用于捆绑:

    {
      "scripts": {
        "build": "yarn build:sdk && rollup -c"
      }
    }
    
  5. 你得跑开 yarn 在子模块内 javascript-sdk 还:

    # 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 仓库。 。 。 .

皈依快乐!


贷项

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

版本与发布记录

@convertcom/js-sdk 共发布 38 个版本,首次发布于 2023/04/10;过去 12 个月发布了 8 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.0.2latest2026/09/171 个月前
5.0.12026/08/103 个月前
5.0.02026/07/253 个月前
4.4.32026/06/065 个月前
4.4.22026/05/265 个月前
4.4.12026/05/265 个月前

关于 @convertcom/js-sdk 的常见问题

如何安装 @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 和提交记录判断。