自定义事件通过 API 触发自动化流程（Automation）工作流程，并传递额外数据以实现个性化。每个事件都可以包含自定义字段，例如跟踪号、产品详情或评论链接，以用于工作流（Workflow）内容。
虽然标准触发器（例如已下订单或废弃购物车（Abandoned Cart））涵盖常见事件，但自定义事件让您能够自动化独特的行为，例如提交评论或创建礼品卡，这些行为超出了 Omnisend 的内置触发器。
注意： 使用最新支持的 API 版本进行自定义事件。 API v3 和 API v5 已被弃用。请勿使用任一版本开始新的集成。
如果您的自定义集成使用自己的 API 密钥调用 API v3 或 v5，Omnisend 可能会在您的帐户中显示警告。请遵循迁移指南以更新您的集成。API v5 将于 2027 年 6 月 30 日 停止服务。
开始之前
当您 将您的商店与 Omnisend 集成 时，一组 标准事件 可用，包括订阅营销、下单和放弃购物车。如果您想触发不同类型操作的工作流，您需要使用 自定义事件。
自定义事件可以是：
通过 API 手动创建，或
通过与 第三方应用 的集成自动添加。
如果您之前没有使用过 API，我们强烈建议您请开发人员帮助设置自定义事件。
API 文档解释了集成如何工作，但开发人员最适合使用提供的技术细节正确实施。
自定义事件仅在 至少触发一次后 出现在自动化触发器下拉菜单中。
自定义事件需要一个 已识别的联系人（电子邮件或电话号码）才能工作。匿名访客将返回 400 错误。
4a1 第三方工具添加的自定义事件示例
创建自定义事件
要使自定义事件开始工作，您需要将其添加到您的 Omnisend 帐户并在第三方端进行设置。
步骤 1. 访问自定义事件。
导航到 商店设置 7 API 7 自定义事件 7 点击 创建自定义事件 开始。
步骤 2.通过 API 文档进行设置。
您将被重定向到 API 文档，您的开发人员可以完成设置并创建自定义事件。在这里，您需要：
选择 最新版本 作为 API 参考 版本；
导航到 事件 API → 事件 → 发送客户事件。
步骤 3. 复制 API 密钥。
转到 商店设置 → API → 创建 API 密钥 并复制您的 API 密钥。
步骤 4.将 API 密钥添加到头部。
在 API 文档中，选择 头部 并将您的 API 密钥粘贴到 头部 字段中。
步骤 5。完成主体参数。
按照向导输入所需的事件详细信息：
联系人 – 您必须至少包含一个联系人标识符：您要传递事件的联系人的电子邮件地址或电话号码。
事件 ID – 例如，
60ba330da4a60c8ed682c5bd:事件名称 – 例如，
评论已提交；事件时间 - 可选。如果使用，它必须是过去或现在 的日期。未来的日期将导致事件失败。
事件版本 - 可选。可以为空以用于自定义事件。
来源 - 这应该始终 设置为
"api"属性 (可选) – 添加任何附加数据以个性化您的工作流 (请参见下面的示例结构。
完成后，单击 尝试一下 创建事件。
步骤 6。 测试您的事件。
验证事件创建：
在单击 "尝试一下" 后检查 API 响应中的 200 状态代码。
前往 商店设置 7 API 7 自定义事件 确认事件出现在您的列表中。
如果您遇到错误，请检查 商店设置 7 API 7 API 日志 以获取详细信息。
4A1 触发测试事件：
使用 POST /events 端点手动触发事件。这使其出现在自动化触发器中。
重要说明：
要编辑自定义事件，您必须删除现有事件并使用 API 文档创建新事件。
禁用自定义事件 将停止其功能，任何使用它作为触发器的自动化将被中止。
重新启用自定义事件 不会不会自动重新激活相关的工作流。您必须手动重新启用自动化。
删除为自定义事件创建的 API 密钥 将导致您的事件失败。
添加事件属性
属性(在 Omnisend 中也标记为 自定义字段)为每个事件传递附加数据（例如，产品名称、跟踪 URL、评论评分）。这些数据可以用于工作流过滤器、拆分条件和消息个性化。
要添加事件属性，请转到 属性 aa属性对象。输入 属性名称 和其 值。要包含附加属性，请单击 添加字段，然后输入下一个属性名称及其值。
一旦您的自定义事件传递给 Omnisend，您可以通过转到 商店设置 → API → 自定义事件 来查看同步的事件属性。
单击 事件名称 以查看相关的 自定义字段。
注意： 一旦自定义事件同步到 Omnisend，事件属性将显示在界面中。自定义字段。这些术语指的是相同的数据；唯一的区别是使用的标签，具体取决于您是在 API 文档中查看它们还是在 Omnisend 中查看。
重要说明：
属性名称 是用于引用自动化和消息个性化中数据的内部标签。
事件创建后，属性名称不能更改。要更新属性名称，删除并重新创建事件。
属性值可以随时间变化，通过发送具有更新值的新事件。
示例： 如果一个联系人留下 1 星评论，请发送一个事件，内容为
reviewType: "1 star"。如果他们后来将其更新为 2 星，请发送一个新事件，内容为reviewType: "2 stars"。
您不能在单个属性中传递 多个值（例如，
"1 star, 2 stars"）。每个值更改发送一个事件。属性字段唯一支持的值类型是 字符串。
🔁 我们建议咨询您的开发人员或第三方集成提供商，以确定每个自定义字段的正确数据格式。
在自动化中使用自定义事件
步骤 1：创建工作流。
转到 自动化 aa创建工作流 aa从头开始创建。
在触发器下拉菜单中，找到您的 自定义事件。
步骤 2：配置工作流设置。
一旦您添加了自定义事件触发器，所有工作流设置将填充来自事件的数据：
步骤 3：个性化消息内容
您可以使用自定义字段数据来 个性化您的消息内容，包括电子邮件、短信和推送通知。
如果您将 链接 作为事件属性传递，您还可以在电子邮件中使用它与 按钮。
在自动化中使用退订链接
当使用 自定义事件 触发自动化工作流时，页脚内容块默认包含 退订链接。
我们建议在所有消息中包含此链接。但是，如果消息是 交易性（例如，与客户下的订单相关），则 不是必需的。
故障排除
问题 1：自定义事件未出现在自动化触发器下拉菜单中。
这是预期的，因为事件仅在至少触发一次后才会出现在自动化触发器列表中。
使用 POST /events 端点手动触发事件。这使其出现在自动化触发器中。
问题 2：触发事件时出现 400 错误。
400 错误 表示 有效负载相关问题，这意味着发送到 Omnisend 的请求无效。这些错误源于 发送方，而不是来自 Omnisend。
要解决此问题，请转到 商店设置 aaAPI aaAPI 日志，并查看 400 错误。
4a1 您可以使用下拉过滤器仅显示 400 级错误。
问题 3：Shopify Flow 自定义字段未出现。
Shopify Flow 使用与标准 Omnisend API 不同的端点和 JSON 结构，因此自定义字段可能不会如预期那样出现。
要解决此问题：
在 Shopify Flow 操作中映射字段时，请使用
{{}}模板变量语法。确保字段名称与 商店设置 API 自定义事件 中定义的完全匹配（区分大小写）。
请记住：Shopify Flow 事件不会出现在 Omnisend 的 API 日志中，这是预期的行为。
有关完整的设置说明，请参阅 将 Shopify Flow 与 Omnisend 集成 文章。
问题 4：事件曾经正常工作，但现在没有触发。
如果您的事件突然停止触发：
前往 商店设置 f API f 自定义事件 检查事件是否仍然启用。
如果事件被 删除，您需要重新创建它并更新任何使用它作为触发器的工作流。
查看 API 日志 在 商店设置 API API 日志 中以获取最近的错误或失败请求。
常见问题
为什么 API 文档称它们为 "事件属性"，而 Omnisend 称它们为 "自定义字段"？
这是 API 文档与 Omnisend 界面之间的术语差异。当您在 API 文档中创建事件属性时，它们会同步到 Omnisend，并在自动化工作流、触发器、分割和消息个性化中显示为 自定义字段。这两个术语指的是相同的数据：与每个自定义事件一起传递的附加信息。
联系自定义属性和事件属性之间有什么区别？
联系 自定义属性存储在联系人资料上，并随着时间的推移而保留。它们通过
customProperties 对象传递在事件有效负载的 contact 对象块中。这些值在联系人资料上可见，并可以在活动、自动化和细分中重复使用。事件属性，另一方面，是在
事件的属性块。它们仅与触发的事件相关联，标记为自定义字段，并且不会在联系人资料上保留。这些对于事件特定条件非常有用，例如在自动化工作流中按产品名称、评审分数或订单总额进行过滤。
我可以在创建事件后编辑事件属性的名称吗？
否 属性名称在事件创建后不能更改。如果您需要重命名属性，您需要删除现有事件并使用更新的属性名称创建新事件。
注意： 删除活动事件将禁用使用它作为触发器的任何工作流。
我应该使用哪个 API 版本来处理自定义事件？
使用当前 API 文档中显示的最新支持的 API 版本。API v3 和 API v5 已被弃用。
我可以在事件属性中传递 URL 吗？
是的。 URL 可以作为字符串值传递在事件属性中。它们可以在自动化过滤器、拆分条件、细分规则中使用，或直接在消息内容中使用个性化变量，如 [[event.referralLink]]。
如需有关自定义事件的进一步帮助，请随时通过 [email protected] 或通过应用内聊天与我们联系。