# @chordcommerce/analytics 中文文档 规范地址：https://npmcn.com/package/%40chordcommerce/analytics/ 版本：1\.24\.5 npm 元数据更新时间：2026-10-30T16:52:30.566Z 中文译文更新时间：2026-11-09T14:37:37.097Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40chordcommerce/analytics 原文对照：https://npmcn.com/package/%40chordcommerce/analytics/?lang=original 项目主页：https://github.com/chordcommerce/chord-pixel#readme 源码仓库：https://github.com/chordcommerce/chord-pixel ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.3 MB，108 个文件 - 模块格式：ES Module - TypeScript 类型：包内自带 - 运行依赖：3 个 - 首次发布：2024-03-04T18:18:03.953Z - 最新版本发布：2026-10-30T16:52:30.376Z - 近 30 天下载量：3710（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：47（近 12 个月 25 个） ## 中文简介 弦商务活动跟踪 ## 安装 ```sh npm install @chordcommerce/analytics ``` 也可以使用：`pnpm add @chordcommerce/analytics`、`yarn add @chordcommerce/analytics`、`bun add @chordcommerce/analytics` ## README # @和弦商业/分析 这个 `@chordcommerce/analytics` 库提供了从您网站向 Chord 发送跟踪事件的简单方法,并带有可选调试模式来验证事件属性. 访问 [(原始内容存档于2018-09-26). docs.chord.co](https://docs.chord.co/installing-chord-analytics) 用于指南、示例和API参考. ## 所需资源 库支持通过 Cord CDP 或 分部发送事件 。 如果使用线段, [分析.js](https://www.npmjs.com/package/@segment/analytics-next) 必须在您的工程中安装 . ## 安装 要安装 `@chordcommerce/analytics`,在工程目录中运行以下命令: ```bash npm install @chordcommerce/analytics # or yarn add @chordcommerce/analytics ``` ## 使用量 初始化 `@chordcommerce/analytics` 内容如下: ```jsx import ChordAnalytics from '@chordcommerce/analytics' const chord = new ChordAnalytics(options) // see below for configuration options chord.trackCartViewed({ cart }) // sends a "Cart Viewed" event to the CDP ``` ### 普通JS 导入 如果您正在使用更古老的节点JS ( window.analytics`。 。 。 . | | `cdpDomain` | 虚假 | _使用 CDP 时需要 ._ 和弦CDP域名. 由和弦队提供. | | `cdpWriteKey` | 虚假 | _使用 CDP 时需要 ._ 和弦CDP写出密钥. 由和弦队提供. | | `debug` | 虚假 | 默认为 `false`当设置为 `true`事件根据Chord的追踪计划进行验证 错误被记录下来 验证使用zod 4. 我们建议为发展和使生产丧失能力创造条件. | | `enableLogging` | 虚假 | 默认为 `true`当设置为 `true`,使用 `console.log`。 。 。 . | | `formatters` | 真实 | 用于构建跟踪事件的函数. 格式化器,对象和事件有两种. `formatters.objects` 需要时间。 详情见下文. | | `metadata` | 真实 | 事件元数据。 详情见下文. | | `namespace` | 虚假 | 默认为 `chord`. 在全球有和弦(例如:. `window.chord`) (中文(简体) ). _仅在使用和弦CDP时适用._ | | `stripNull` | 虚假 | 默认为 `true`当设置为 `true`,带有 `null` 删除值。 CDP 通常治疗 `null` 财务报告和审定财务报表 `undefined` 作为单独的值,请确定您是否打算发送 `null` 值在设置为虚假之前. | 若为 `cdp`, (中文(简体) ), `cdpDomain`,以及 `cdpWriteKey` 全部省略,不发送跟踪事件. **元数据** | 财产 | 需求 | 说明 | | --- | --- | --- | | `metadata.i18n.currency` | 真实 | ISO 4217货币代码中的顺序货币,大写. 譬如说, `USD`。 。 。 . | | `metadata.i18n.locale` | 真实 | 户口令. 譬如说, `en-US`。 。 。 . | | `metadata.ownership.omsId` | 真实 | 由 Cord 指定的 UUID . | | `metadata.ownership.storeId` | 真实 | 由 Cord 指定的 UUID . | | `metadata.ownership.tenantId` | 真实 | 由 Cord 指定的 UUID . | | `metadata.platform.name` | 真实 | 使用的电子商务平台. 譬如说, `Shopify`。 。 。 . | | `metadata.platform.type` | 真实 | 事件起源地的平台类型. 无论是 `web` 或者说 `pos`。 。 。 . | | `metadata.store.domain` | 真实 | 事件发源地的网站域. 对Shofify来说,这应该是之前的商店口水 `.myshopify.com`。 。 。 . | ### 格式化器 格式化器是用于构建跟踪事件属性的Javascript函数. 格式化器,对象和事件有两种. 您必须定义对象格式。 事件格式化是可选的 。 见 [和弦的文档](https://docs.chord.co/analytics-getting-started#fgWx7) 用于更多细节和示例格式. **对象格式** 必须为Chord事件中使用的四个核心数据类型中的每一类提供一个格式。 此 formatter 函数将输入数据转换为 Cord 所期望的类型 。 见 [和弦的文档](https://docs.chord.co/analytics-getting-started#XhUB5) 关于对象格式的更多细节. | 财产 | 需求 | 说明 | | --- | --- | --- | | `formatters.objects.cart` | 真实 | 创建拖车对象的函数 . | | `formatters.objects.checkout` | 真实 | 创建取出对象的函数 . | | `formatters.objects.lineItem` | 真实 | 创建行项对象的函数. | | `formatters.objects.product` | 真实 | 一个创建产品对象的函数. | **事件格式** 可为每次活动提供前题。 此 formatter用于在Cord构造事件之后,即发送到CDP之前,转换特定事件的事件属性. 见 [和弦的文档](https://docs.chord.co/analytics-getting-started#jquZe) 关于事件格式化的更详细信息. ## 使用打字符 可选的,你可以即兴表演 `ChordAnalytics` 带有自定义类型参数来描述您的数据,以改善格式化器和SDK函数的类型安全. 例如,如果你在工作 对象喜欢 `cart`, (中文(简体) ), `product`例如,从 Shopify storefront API 查询中,您可能已经具备了类似类型 `StorefrontCart` 为响应定义。 证据 `ChordAnalytics` 有类型参数 : ```js interface ObjectTypes { Cart: StorefrontCart Checkout: StorefrontCart LineItem: StorefrontLineItem Product: StorefrontProduct } const chord = new ChordAnalytics({ options }) ``` 现在,当你使用 SDK 方法像 `chord.trackCartViewed({ cart })`, (中文(简体) ), `cart` 拥有 `StorefrontCart` 类型. Formatter 类型也支持函数参数的可选通用类型参数: ```js import type { CartFormatter } from '@chordcommerce/analytics' export const cartFormatter: CartFormatter = (props) => { const { cart } = props // `cart` has type `StorefrontCart` return { ... } } ``` 添加 SourceMiddle 软件( 英文: AnalyticsMiddleware) 注册一个中间软件功能,以便在事件属性出现之前对其进行修改 发送到分析提供者。 Middleware 函数按顺序被引用 在事件跟踪过程中添加了,并且将每个人的属性合并到 按顺序排列. 中间软件可以是同步的,也可以是同步的. 同步的中间软件永远不会 等待,所以不会给活动交付增加任何延误。 一个同步的中间软件是 等待事件发送, 封顶三秒钟—— 一个中间软件 未解决则放弃, 警告会被记录, 事件会被发送 没有它的属性。 投出或拒绝的中间软件会被记录 跳过 中间软件从不阻止事件被发送. 参数 - func (Analytics Middleware) - 接收事件的中间软件函数 数据,并可以返回额外的属性以合并到事件有效载荷. 返回值 中间软件函数可以返回 : - 部分 - 合并到事件有效载荷的属性 - 无效 - 无要添加的属性 - 上述任何一人的诺言 -- -- 在事件发出之前等待 这个 `payload` 参数带有 `payload.obj` (事件属性、名称和 页面上下文)加 `payload.userId` 财务报告和审定财务报表 `payload.anonymousId` 作为发展政策委员会 目前认识它们,也可能是未定义的. 注意中间软件通过 **返回时** 他们。 改变 `payload` 论据没有效果; `next` 已接受签署 兼容而无所为. 使用示例 ``` analytics.addSourceMiddleware(({ payload }) => { const { searchParams } = payload.obj.context.page; return { utm_source: searchParams.utm_source, utm_medium: searchParams.utm_medium, utm_campaign: searchParams.utm_campaign }; }); analytics.addSourceMiddleware(({ payload }) => { return { session_id: getSessionId(), user_agent: navigator.userAgent, timestamp: Date.now() }; }); // Asynchronous middleware: the event waits for the lookup, up to three seconds. analytics.addSourceMiddleware(async ({ payload }) => { if (payload.obj.event !== 'Order Completed') return; const isNewCustomer = await fetchIsNewCustomer(); return { is_new_customer: isNewCustomer ? 1 : 0 }; }); ``` ## API 参考 见 [和弦的文档](https://docs.chord.co/api-reference) 对于一个完整的 API 参考. ## 释放 此软件包使用 [语义释放](https://github.com/semantic-release/semantic-release) 实现版本和出版的自动化。 发布会自动被触发——不需要手动的版本出出凸出或发布步骤. ### 如何运作 Repo有单一的CI工作流程(`.github/workflows/ci.yml`有两个工作: 1. **`test`** ——对所有包进行涂装,更美,构建和测试. 每一次推入的触发器 `main`编号 :`beta` 和每一个拉请求. 2. **`release`** ——只运行 `main` 财务报告和审定财务报表 `beta` 分支, 之后 `test` 通过。 运行 `semantic-release` 以确定是否应当发布新版本. 释放流 : 1. 将 PR 合并到 `main` (稳定)或 `beta` (释前. 2. 这个 `test` 任务运行。 如果它通过了 `release` 任务开始. 3. `semantic-release` 分析自上次发布标记以来的传输消息. 4. 如果可再放行承诺存在,则包会被发布到npm和GitHub套件,ChangGELOG.md更新,并创建一个Git标签. 5. 如果不存在可释放的罪行, `semantic-release` 出口干净,没有发布. ### 公关产权必须遵循传统承诺 当使用 GitHub 时 **壁球合并** (默认),PR标题成为壁球承诺消息的第一行. 语义 - 释放只描述 **第一行 :** 以确定版本的凸起,所以 **pR 标题必须使用常规承诺前缀** (例如, `fix: resolve consent race condition`) (中文(简体) ). 个人承诺信息在公关机构被忽略. 如果PR标题没有从可放出前缀开始,即使个人在 PR 使用 内做出 ,也不会发布 `fix:` 或者说 `feat:`。 。 。 . ### 当一个释放发生( 当它没有) 发行发行 **仅限** 当所有三个条件都得到满足时: 1. 一个推地上 `main` 或者说 `beta` (通过合并公关或直接推) 2. 测试通过 3. 自上次发布标记后,有新的承诺,并附有可重放的前缀(对照 **第一行 :** (每个承诺消息) **可放行承诺前缀** (这些触发一个版本的凸起): | 前缀 | 版本弹出 | 示例 | | --- | --- | --- | | `fix:` | 补丁(1.0-1.0.1) | `fix: resolve race condition in consent adapter` | | `feat:` | 次要( 1. 0.0- 1. 1.0) | `feat: add trackOrderCompleted method` | | `BREAKING CHANGE:` 体内 | 主要项目(1.0-2.0) | 提交正文包含 `BREAKING CHANGE: remove legacy API` | **不可释放的前缀** (这些不会引发释放): `chore:`, (中文(简体) ), `ci:`, (中文(简体) ), `docs:`, (中文(简体) ), `refactor:`, (中文(简体) ), `test:`, (中文(简体) ), `style:`, (中文(简体) ), `build:`, (中文(简体) ), `perf:` 如果合并为 `main` 或者说 `beta` 仅包含不可释放的承诺,释放任务运行,但 `semantic-release` 确定不需要发布,无需发布即可退出. ### 单项范围界定 此还原使用 [语义 -- -- 释放 -- -- 莫诺雷波](https://github.com/pmowrer/semantic-release-monorepo) 将范围释放到单个包中。 只承诺在软件包目录中触摸文件(例如, `packages/core/`在决定下一个版本时考虑。 A 类 `feat:` 承诺只修改 `.github/workflows/` 或另一个软件包的目录将 **没有** 触发释放 `@chordcommerce/analytics`。 。 。 . ### 释放前 合并为 `beta` 创建发行前版本(例如, `1.22.0-beta.1`) (中文(简体) ). 在推广到 `main`。仅限 `main` 财务报告和审定财务报表 `beta` 目前配置用于CI工作流程中的自动发布。 额外的预放分行(例如, `alpha`)可以通过将它们添加到工作流程的分支过滤器中来启用 `ci.yml` 和语义释放分支配置. ### Beta 发布工作流程 1. 关闭特性分支 `beta` 并做你的工作。 做你的工作. 2. 创建针对 `beta` 分支并合并它. 3. CI工作流程运行测试,然后 `semantic-release` 发布β版本(例如, `1.22.0-beta.1`) (中文(简体) ). 4. 安装方式 : `npm install @chordcommerce/analytics@beta` ### 将β推广到生产 1. 从 `beta` → `main` 并合并它. 2. CI工作流程运行测试,然后 `semantic-release` 在 `main`。 。 。 . ### 干线运行 您可以通过手动触发 GitHub Actions 中的 CI 工作流程, 预览发布后会做什么 `dryRun` 设置为 `true`。 。 。 . ## 支助 关于设置和配置的支持,请直接联系Chord at **[帮助@ chord.co](mailto:help@chord.co)**。 。 。 . ## 常见问题 ### @chordcommerce/analytics 是什么？ 弦商务活动跟踪 ### 如何安装 @chordcommerce/analytics？ 在项目目录运行 npm install @chordcommerce/analytics，或使用 pnpm add / yarn add / bun add。 ### @chordcommerce/analytics 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @chordcommerce/analytics 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @chordcommerce/analytics 可以商用吗？ @chordcommerce/analytics 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @chordcommerce/analytics 的下载量有多少？ 根据 npm 官方下载统计，@chordcommerce/analytics 在 2026/10/10 – 2026/11/08 这 30 天内被下载 3,710 次，日均约 124 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @chordcommerce/analytics 还在维护吗？ 最新版本 1\.24\.5 发布于 2026/10/31（9 天前）；至今共发布 47 个版本，其中过去 12 个月发布了 25 个；首次发布于 2024/03/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。