@和弦商业/分析

这个 @chordcommerce/analytics 库提供了从您网站向 Chord 发送跟踪事件的简单方法,并带有可选调试模式来验证事件属性.

访问 (原始内容存档于2018-09-26). docs.chord.co 用于指南、示例和API参考.

所需资源

库支持通过 Cord CDP 或 分部发送事件 。 如果使用线段, 分析.js 必须在您的工程中安装 .

安装

要安装 @chordcommerce/analytics,在工程目录中运行以下命令:

npm install @chordcommerce/analytics
# or
yarn add @chordcommerce/analytics

使用量

初始化 @chordcommerce/analytics 内容如下:

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 (<v11) 或 Webpack, 使用上述 ES6 导入的导入可能会失败 。 您可以使用普通JS导入 :

const { ChordPixel } = require('@chordcommerce/analytics/dist/cjs')

配置

@chordcommerce/analytics 可通过下列选项初始化:

若为 cdp, (中文(简体) ), cdpDomain,以及 cdpWriteKey 全部省略,不发送跟踪事件.

元数据

格式化器

格式化器是用于构建跟踪事件属性的Javascript函数. 格式化器,对象和事件有两种. 您必须定义对象格式。 事件格式化是可选的 。 见 和弦的文档 用于更多细节和示例格式.

对象格式

必须为Chord事件中使用的四个核心数据类型中的每一类提供一个格式。 此 formatter 函数将输入数据转换为 Cord 所期望的类型 。 见 和弦的文档 关于对象格式的更多细节.

事件格式

可为每次活动提供前题。 此 formatter用于在Cord构造事件之后,即发送到CDP之前,转换特定事件的事件属性. 见 和弦的文档 关于事件格式化的更详细信息.

使用打字符

可选的,你可以即兴表演 ChordAnalytics 带有自定义类型参数来描述您的数据,以改善格式化器和SDK函数的类型安全.

例如,如果你在工作 对象喜欢 cart, (中文(简体) ), product例如,从 Shopify storefront API 查询中,您可能已经具备了类似类型 StorefrontCart 为响应定义。 证据 ChordAnalytics 有类型参数 :

interface ObjectTypes {
  Cart: StorefrontCart
  Checkout: StorefrontCart
  LineItem: StorefrontLineItem
  Product: StorefrontProduct
}

const chord = new ChordAnalytics<ObjectTypes>({ options })

现在,当你使用 SDK 方法像 chord.trackCartViewed({ cart }), (中文(简体) ), cart 拥有 StorefrontCart 类型.

Formatter 类型也支持函数参数的可选通用类型参数:

import type { CartFormatter } from '@chordcommerce/analytics'

export const cartFormatter: CartFormatter<StorefrontCart> = (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 参考

见 和弦的文档 对于一个完整的 API 参考.

释放

此软件包使用 语义释放 实现版本和出版的自动化。 发布会自动被触发——不需要手动的版本出出凸出或发布步骤.

如何运作

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. 自上次发布标记后,有新的承诺,并附有可重放的前缀(对照 第一行 : (每个承诺消息)

可放行承诺前缀 (这些触发一个版本的凸起):

不可释放的前缀 (这些不会引发释放):

chore:, (中文(简体) ), ci:, (中文(简体) ), docs:, (中文(简体) ), refactor:, (中文(简体) ), test:, (中文(简体) ), style:, (中文(简体) ), build:, (中文(简体) ), perf:

如果合并为 main 或者说 beta 仅包含不可释放的承诺,释放任务运行,但 semantic-release 确定不需要发布,无需发布即可退出.

单项范围界定

此还原使用 语义 -- -- 释放 -- -- 莫诺雷波 将范围释放到单个包中。 只承诺在软件包目录中触摸文件(例如, 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。 。 。 .