服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务,不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动,严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外,不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- Admin UI 扩展需要 API 2027-01 或更新版本;嵌入式 App Home 使用 App Bridge。
- should-render 和数据目标无法发送事件。
- 两类入口都允许突发最多 20 条,之后每秒 2 条,计数范围不同。
- 后台 UI 事件可用于观察应用使用情况,Shopify App Pricing 用量应按后端计费事件上报。
先确认事件从哪个界面发出
如果代码运行在 Admin UI 扩展,检查 shopify.extension.toml 的 api_version 是否为 2027-01 或更新版本。较早版本没有 shopify.appEvents。即使版本正确,should-render 和数据目标也不发送事件;这类调用会返回 success: false,错误提示 Emit is unavailable。
嵌入式 App Home 需要加载 App Bridge。Shopify 这次没有给此入口指定 Shopify API 版本。若 App Bridge 尚未完成与后台的握手,Promise 可能仍在等待。把使用情况事件与保存、页面跳转等操作分开,避免让商家等待这条日志。
把 emit 结果与 Shopify 的日志分开核对
用开发店铺和 shopify app dev 走一次实际页面操作,记录测试时间、测试店铺和事件名称。如果 emit 返回 success: false,先读 error,核对是否是目标不可用、属性无效或触发限流。返回 success: true 后,再去 Dev Dashboard → Logs,按 App Event 类型、时间和店铺查找。
如果后台先接受但 Logs 没有记录,Shopify 仍可能未收到,或在后续验证时丢弃。检查应用在该店铺的安装状态、会话是否有效、名称格式和属性。自定义事件可使用 report_exported 之类的名称。只有已声明且符合官方标准事件定义时才使用相应的 shopify. 名称。
排查突发发送和事件字段
Admin UI 扩展各自允许突发最多 20 条,之后每秒 2 条。嵌入式 App Home 的同一应用在一个 Shopify 后台标签页中使用相同额度,页面、弹窗和应用意图共享。连续渲染或双击可触发多次发送,应围绕一次实际完成的操作只发一次。
发送报表导出事件时,可记录格式和行数等非个人字段。属性最多 15 个键,键最长 64 个字符,字符串值最长 128 个 UTF-8 字符。使用字符串、数字或布尔值,省略数组、嵌套对象,以及名字、邮箱、员工 ID 和客户 ID 等可识别个人的信息。
把使用日志和账单核对分开
例如,商家完成一次报表导出,可以发送 report_exported 来复盘功能使用情况。后台 UI 发送的事件不会用于 Shopify App Pricing 计费。需要上报可计费使用量时,在应用后端遵循 Shopify 对计费事件的要求。
建议保留一条开发店铺验收记录,包含界面类型、扩展版本或 App Bridge、事件名称、本次返回值和 Logs 中是否看到记录。如果应用要验证计费结果,单独查看后端计费事件的处理状态。
资料来源
常见问题
success: true 可以当作送达凭证吗?
它表示 Shopify 后台接受这次发送。要确认送达,检查对应店铺和时间范围内的 Dev Dashboard Logs。
App Home 也必须切换到 2027-01 吗?
2027-01 或更新版本是 Admin UI 扩展的条件。嵌入式 App Home 通过 App Bridge 使用该接口,公告没有给它设置同样的 API 版本要求。
为什么表单保存不应该等待 emit?
App Home 本次调用可能仍在等待 App Bridge 握手。把应用使用记录放在商家操作的完成路径之外,可以降低保存或跳转被延迟的风险。