应用事件：从结账和顾客账户 UI 扩展发送事件

从 API 版本 2027-01 开始，结账和用户账户 UI 扩展程序可以通过 shopify.appEvents.emit() 向 Shopify 发送 应用事件。扩展程序无需网络访问权限或应用后端即可发送事件。这是一个新的可选 API，因此无需采取任何操作。

变更内容

新的 shopify.appEvents.emit() 方法会发送带有事件句柄和可选属性的自定义事件。Shopify 会在每个事件中自动添加你的应用和商店信息，因此你无需提供访问令牌或商店 ID。事件将显示在你的 开发者仪表板日志 中，与你通过 应用事件 API 发送的事件一起展示。有关参数、返回值和速率限制，请参阅 结账 UI 扩展程序 和 用户账户 UI 扩展程序 的 API 参考文档。

你的扩展程序还可以发送你为 Shopify 分析 声明的标准事件。商家可以在其分析工具中看到这些事件。

结账和顾客账户仅在买家允许进行数据分析处理后才发送事件。在此之前，事件会保留在页面上。如果买家拒绝或离开页面，则保留的事件不会发送。

每个扩展程序可以突发发送 20 个事件，随后每秒发送 2 个事件。当 emit() 无法发送事件时，它将返回 {success: false, error}。例如，当事件无效或扩展程序超出速率限制时就会发生这种情况。请勿在事件属性中包含个人信息。

UI 扩展程序发送的事件不用于计费处理。若要为 Shopify 应用定价 报告使用情况，请继续从应用后端发送计费事件。

受影响范围

此变更适用于使用 API 版本 2027-01 或更高版本的结账 UI 扩展程序和用户账户 UI 扩展程序。早期 API 版本的扩展程序不具备 shopify.appEvents。

服务器应用事件 API 未发生变化，且没有这些扩展的应用不受影响。Shop 应用中的结账流程不会从扩展中发送事件。

为何重要

在此次变更前，扩展需要网络访问权限和应用后端才能发送应用事件。现在，扩展可以直接发送事件，因此您可以将买家使用您扩展的情况与您应用的其他活动一起查看。

操作步骤

无需采取任何操作。要从扩展发送事件，请执行以下步骤：

1. 在扩展程序的 shopify.extension.toml 文件中将 api_version 设置为 2027-01。
2. 在扩展程序中事件发生的位置调用 shopify.appEvents.emit()。
3. 在开发商店中，将扩展添加到结账或顾客账户页面。
4. 如有必要，请以买家身份允许分析处理并进行测试购买。确认该事件出现在你的开发者仪表板日志中。如果你发送了已声明的标准事件，还可以在开发商店的 Shopify 管理后台的 分析 中找到它。

shopify.appEvents.emit("offer_viewed", { offer_id: "summer_bundle", placement: "order_summary", });

相关文档

• 关于应用事件
• 从结账 UI 扩展发送事件
• 从顾客账户 UI 扩展发送事件