自定义事件通过 API 触发自动化流程（Automation）工作流程，并传递额外数据以实现个性化。每个事件都可以包含自定义字段，例如跟踪号、产品详情或评论链接，以用于工作流（Workflow）内容。

虽然标准触发器（例如已下订单或废弃购物车（Abandoned Cart））涵盖常见事件，但自定义事件让您能够自动化独特的行为，例如提交评论或创建礼品卡，这些行为超出了 Omnisend 的内置触发器。

开始之前

当您将您的店铺与 Omnisend 集成时，一组标准事件将可用，包括订阅营销、下达订单和废弃购物车（Abandoned Cart）。如果您想针对不同类型的操作触发条件（Trigger）一个工作流（Workflow），您将需要使用自定义事件。
Custom Events 可以是：
- 手动通过 API 创建，或；
- 通过与第三方应用的集成自动添加。
Omnisend 支持并建议仅使用 API v5 用于 Custom Events。早期版本，例如 v3，仍然可用，但不再获得积极支持。
如果您之前没有使用过 API，Omnisend 强烈建议让开发人员参与，协助设置自定义事件。
- API 文档解释了集成如何工作，但开发人员最适合使用提供的技术细节正确地实施它。
自定义事件至少被触发一次后，才会显示在自动化流程（Automation）触发条件（Trigger）下拉菜单中。
自定义事件需要一个已识别的联系人（电子邮件（Email）或电话号码）才能正常工作。匿名访客将返回 400 错误。

💡 第三方工具添加的自定义事件示例

AfterShip: 信息已接收– 当订单发货时，触发工作流（Workflow）。
- 自定义字段（Custom Field）：追踪号码，追踪网址。
Intercom: 评价已创建– 当联系人给支持代理留下评论时，触发工作流（Workflow）。
- 自定义字段（Custom Field）：评分，评论内容。
Growave: Wishlist 补货通知– 当心愿单商品重新有货时，触发工作流（Workflow）。
- 自定义字段：产品详情
Junip: 评论已创建– 当产品评论提交时，触发工作流（Workflow）。
- 自定义字段：产品信息，评论提交链接。

创建自定义事件

要使自定义事件开始工作，您需要将其添加到您的 Omnisend 账户并将其在第三方进行设置。

步骤 1.访问 Custom Events

前往 店铺设置 → API → 自定义事件 → 点击 "Create custom event" 开始使用。

第 2 步。通过 API 文档设置。

您将被重定向到 API 文档，您的开发人员可以在其中完成设置并创建自定义事件。在此，您需要：

选择 v5 作为 API 参考版本；
前往 Events API → Events → Send Customer event.

步骤 3.复制 API密钥（API Key）。

前往店铺设置 → API → 创建API密钥（API Key）并复制您的API密钥（API Key）。

步骤 4. 添加 API密钥（API Key）到标头。

在API文档中，选择Header并粘贴您的API密钥（API Key）到Header字段中。

步骤 5.完成 Body Params。

请按照向导输入所需的事件详情：

联系人 – 您必须至少包含一个联系人标识符：您希望通过事件传递的联系人的电子邮件地址或电话号码。
- 您还可以包含其他数据，例如地址、标签、出生日期或自定义属性。这些数据存储在联系人资料中，并长期保留。
事件 ID – 例如，60ba330da4a60c8ed682c5bd:
事件名称 – 例如，评论已提交；
事件时间 -可选。如果使用，它必须是过去或现在的日期。未来的日期将导致事件失败。
事件版本 - 可选。对于自定义事件，可以留空。
来源 - 这应该始终设置为API
属性 (可选) – 添加任何额外数据以个性化您的工作流（Workflow）(请参阅下面的示例结构)。

完成后，点击 "Try it" 以创建事件。

步骤 6. 测试您的事件。

验证事件创建：

在点击“Try it”后，检查 API 响应中的200 状态码。
前往 店铺设置 → API → 自定义事件 以确认该事件出现在您的联系人名单中。
如果您遇到错误，请查看Store Settings → API → API logs以获取详细信息。

💡 触发测试事件：
使用 POST /events 端点手动触发该事件。这使其显示在自动化流程（Automation）触发条件（Trigger）中。

重要提示：

要编辑自定义事件，您必须删除现有事件，并使用 API 文档创建一个新事件。
禁用自定义事件将使其停止运行，任何将其用作触发条件（Trigger）的自动化都将停止。
重新启用 Custom Event does不会自动重新激活关联的工作流（Workflow）。您必须手动重新启用该自动化流程（Automation）。
删除为自定义事件创建的API密钥（API Key）将导致您的事件失败。

添加事件属性

属性(也称为 自定义字段（Custom Field） 在 Omnisend 中)随每个事件传递额外数据（例如，产品名称、跟踪 URL、评价星级）。此数据可用于工作流（Workflow）筛选器、拆分条件和消息个性化。

要添加事件属性，请前往 Properties → Properties Object。输入属性名称和其值。要包含其他属性，点击 "Add field"，然后输入下一个属性名称及其值。

一旦您的自定义事件传递到 Omnisend，您可以通过前往店铺设置 → API → 自定义事件来查看同步的事件属性。

点击事件名称以查看相关的自定义字段（Custom Field）。

注意：一旦自定义事件同步到 Omnisend，事件属性将显示在界面中，作为custom fields。这些术语指代相同的数据；唯一的区别在于所使用的标签，具体取决于您是在 API 文档中查看它们，还是在 Omnisend 中查看。

重要注意事项：

属性名称是内部标签，用于在自动化和消息个性化中引用数据。
事件创建后，属性名称无法更改。要更新属性名称，请删除并重新创建事件。
属性值会随着时间的推移而更改，通过发送带有更新值的新事件即可实现。
- 示例：如果一个联系人留下 1 星评价，发送一个事件，其中包含reviewType: "1 星"如果他们稍后将其更新为2星，则发送一个新事件，其中包含评价类型: "2 星"
您不能在单个属性中传递多个值（例如，"1 star, 2 stars"）。每次数值变化时发送一个事件。
属性字段唯一支持的值类型是string。

💡 我们建议您咨询您的开发人员或第三方集成提供商，以确定每个自定义字段（Custom Field）的正确数据格式。

在自动化流程（Automation）中使用自定义事件

步骤 1：创建一个工作流（Workflow）。

前往 Automations → 创建工作流（Workflow） → 从头开始创建。

在触发条件（Trigger）下拉菜单中，找到您的自定义事件。

步骤 2: 配置工作流（Workflow）设置。

一旦您添加自定义事件触发条件（Trigger），所有工作流（Workflow）设置将使用来自该事件的数据填充：

触发筛选条件（Trigger Filter） – 根据自定义字段（Custom Field）值进行筛选（这些是您通过 API 定义的事件属性）
Split block – 根据自定义字段（Custom Field）分支工作流（Workflow）。

步骤 3：个性化消息内容

您可以使用自定义字段数据来个性化您的消息内容，包括电子邮件（Email）、短信（SMS）和推送通知。

如果您将链接作为事件属性传递，您也可以在您的电子邮件（Email）中将其与按钮一起使用。

在自动化流程（Automation）中使用退订链接

当使用自定义事件来触发一个自动化流程（Automation）工作流（Workflow）时，页脚内容块默认包含一个取消订阅链接。

建议在所有消息中包含此链接。然而，如果消息是交易性的（例如，与客户下的订单相关），则不是必需的。

重要提示：由自定义事件触发的自动化流程（Automation）工作流将向已取消订阅的联系人发送消息 默认情况下。如果您这样做不希望向已取消订阅的联系人发送消息，更新工作流（Workflow）渠道设置 通过点击触发条件（Trigger）模块并调整偏好设置。

故障排除

问题 1: 自定义事件未显示在自动化流程（Automation）触发条件（Trigger）下拉菜单中。

这是预期的，因为事件只有在至少触发一次后，才会出现在自动化流程（Automation）触发器列表中。

您可以使用 POST /events 端点手动触发事件。这会使其显示在自动化流程（Automation）触发器中。

示例 API 调用 (v5)：

POST https://api.omnisend.com/v5/events
Headers:
  X-API-KEY: your-api-key
  Content-Type: application/json

Body:
{
  "origin": "api",
  "email": "[email protected]",
  "eventName": "Product Back in Stock",
  "fields": {
    "productName": "Blue Widget",
    "productURL": "https://yourstore.com/products/blue-widget"
  }
}

问题2：在触发事件时收到400错误。

一个 400 错误 表示一个 请求体相关问题，这意味着发送到 Omnisend 的请求无效。这些错误源自发件人端，而非 Omnisend。

要解决此问题，请前往店铺设置 → API → API 日志并查看400 错误。

💡 您可以使用下拉筛选器，仅显示 400-level errors。

问题 3：Shopify Flow 自定义字段未显示。

Shopify Flow 使用与标准 Omnisend API 不同的端点和 JSON 结构，因此自定义字段可能不会按预期显示。

要解决此问题：

在 Shopify Flow 操作中映射字段时，请使用 ####{{}} 模板变量语法。
确保字段名称与店铺设置 → API → 自定义事件中定义的完全匹配（它们区分大小写）。
请记住：在 Omnisend 中，Shopify Flow 事件不会出现在 API 日志中，因为这是预期行为。

有关完整的设置说明，请参阅将 Shopify Flow 与 Omnisend 集成文章。

问题 4：事件之前正常运行，现在不触发了。

如果您的事件突然停止触发：

前往店铺设置 → API → 自定义事件 以检查该事件是否仍处于启用状态。
如果事件被删除，您需要重新创建它并更新任何将其用作触发条件（Trigger）的工作流。
查看 API 日志，在 店铺设置 → API → API 日志 下查找近期错误或失败的请求。

常见问题

为什么 API 文档称它们为“事件属性”，但 Omnisend 称它们为“自定义字段”？

这是 API 文档和 Omnisend 界面之间的术语差异。当您在 API 文档中创建事件属性时，它们会同步到 Omnisend 并显示为 自定义字段 在自动化流程（Automation）工作流、触发器、拆分和消息个性化中。这两个术语都指代相同的数据：随每个自定义事件传递的附加信息。

联系人 Custom Properties 和 Event Properties 有什么区别？

联系人自定义属性存储在联系人资料中并随时间保留。它们通过以下方式传递customProperties object 中的event payload 中的联系人 object block。这些值在联系人资料中可见，并且可以在营销活动、自动化和细分受众（Segmentation）中重复使用。
事件属性，则会在事件的属性块它们仅与被触发的事件相关联，被标记为自定义字段，并且不会保留在联系人资料上。这些对于事件特定的条件很有用，例如在自动化流程（Automation）中按产品名称筛选、评论分数或订单总额。