Gadget Framework 1.6 实战：控制 Shopify Webhook 字段自动补齐

在 Shopify 应用开发中，Webhook 可以及时告诉应用“某条数据发生了变化”。

例如，店铺创建了一个客户，Shopify 会发送 Customer Webhook。Gadget 收到 Webhook 后，就可以把客户数据同步到自己的数据库中。

但 Webhook 不一定包含 Shopify 客户模型的全部字段。

如果应用需要某些没有出现在 Webhook 中的字段，Gadget 过去会自动再次请求 Shopify，把缺少的数据补齐。这个过程虽然方便，但如果每次 Webhook 都触发额外请求，就可能增加平台用量和同步成本。

Gadget Framework 1.6 改进了这个流程。开发者现在可以自己决定：

• 某个字段是否加入 Shopify 数据模型。
• Webhook 到达时是否立即获取这个字段。
• 是否等到夜间对账或手动同步时再获取。
• 完全不需要的字段是否从模型中移除。

本文使用 Shopify Customer 模型中的 Email Marketing Consent 和 SMS Marketing Consent 作为示例，演示如何配置 Shopify Webhook 字段同步策略。

这份项目实际演示了什么

演示项目不是一个前台插件

这份字幕演示的是 Gadget Shopify 应用的数据同步配置，不是店铺主题插件，也不是客户账户页面功能。

项目主要验证以下流程：

Shopify 创建客户
→ Shopify 发送 Customer Webhook
→ Gadget 接收 Webhook
→ Gadget 根据字段配置决定是否补齐数据
→ 数据写入 Gadget 数据库

字幕中的测试客户包括：

• Carl Weathers。
• Steve Harvey。

测试时，两位客户都同意接收营销邮件，然后比较不同字段同步配置下的数据结果。

实际验证的两个客户字段

项目重点使用两个 Shopify 客户字段：

Email Marketing Consent
SMS Marketing Consent

Email Marketing Consent 用于记录客户是否同意接收电子邮件营销。

SMS Marketing Consent 用于记录客户是否同意接收短信营销。

这些字段涉及客户营销权限，不能只把它们当作普通客户属性使用。应用在发送营销内容前，仍然需要根据 Shopify 中保存的同意状态和适用的隐私、营销法规进行判断。

使用的技术栈

Gadget Framework 1.6

项目使用 Gadget Framework 1.6。

Framework 1.6 的重点变化是，开发者可以配置 Shopify 模型中非 Webhook 字段的获取方式。

Shopify Customer Webhook

Shopify Customer Webhook 用于通知 Gadget：

• 客户已创建。
• 客户已更新。
• 客户资料发生变化。

Webhook 传递的是事件数据，但不一定包含 Customer 模型中的所有字段。

Gadget Managed Webhooks

Gadget 会根据 Shopify 连接和模型配置，管理相关 Webhook 订阅。

如果应用启用了 Shopify Customer 模型，Gadget 可以自动订阅对应的客户事件，并将收到的数据同步到 Gadget 数据库。

Gadget Shopify Data Sync

Gadget Data Sync 用于从 Shopify 获取数据并同步到 Gadget 数据库。

除了 Webhook 触发的实时更新之外，Gadget 还可以通过数据同步或对账流程补齐之前没有获取的字段。

Shopify Webhook 为什么可能缺少字段

Webhook 不一定包含完整模型

Shopify Webhook 的数据结构取决于具体事件和资源类型。

某些字段可能不会出现在每一次 Webhook Payload 中。例如，字幕使用的 Customer Webhook 中没有直接包含 Email Marketing Consent。

当 Shopify Webhook 没有携带某个字段时，应用有两种选择：

收到 Webhook 后立即向 Shopify 查询缺失字段

或者：

先处理 Webhook，稍后通过同步或对账获取字段

立即补齐并不总是必要

如果应用每次收到客户 Webhook 都自动获取完整客户数据，就可能产生大量额外请求。

但很多应用并不需要在每一次客户更新事件中立即使用营销同意信息。

例如：

• 应用只需要客户 ID。
• 应用只需要客户姓名。
• 应用只需要同步客户创建时间。
• 营销同意信息只在发送营销活动前检查。
• 应用会定期统一同步客户数据。

这种情况下，每次 Webhook 都补齐完整字段，可能是不必要的。

升级到 Gadget Framework 1.6

检查当前 Framework 版本

在 Gadget 项目设置中查看当前 Framework 版本。

字幕中的项目最初使用的是：

Gadget Framework 1.5

然后升级到：

Gadget Framework 1.6

如果你的项目使用 Shopify Market 模型，需要特别检查升级说明。字幕提到 Framework 1.6 对 Shopify Market 模型存在 Breaking Change。

升级前建议：

• 备份当前项目配置。
• 查看 Gadget 当前升级说明。
• 检查 Shopify Market 模型是否正在使用。
• 在开发环境先完成升级。
• 确认 Webhook 和数据同步仍然正常。

执行依赖更新

在 Gadget 中完成 Framework 升级后，按照项目提示更新依赖。

常见操作包括：

yarn

具体命令以当前 Gadget 项目中的升级提示为准。

升级完成后，重新打开 Shopify 模型设置，确认出现非 Webhook 字段配置入口。

添加 Shopify Customer 非 Webhook 字段

打开 Customer 模型

进入 Gadget 的 Shopify Customer 数据模型。

升级到 Framework 1.6 后，可以看到一个用于添加非 Webhook 字段的入口，通常表现为加号按钮或类似：

Add non-webhook fields

这些字段不会默认全部添加到模型中。

这样做的好处是，新的 Gadget 应用不会自动加载一大批可能暂时用不到的 Shopify 字段。

添加 Email Marketing Consent

在非 Webhook 字段列表中找到：

Email Marketing Consent

将这个字段添加到 Shopify Customer 模型。

添加后，Gadget 会显示这个字段的获取方式。

字幕中的字段状态是：

Fetch on Webhook

也就是每次 Customer Webhook 到达时，Gadget 都会尝试获取这个字段。

选择 Fetch on Webhook

Fetch on Webhook 的工作方式

当 Email Marketing Consent 设置为 Fetch on Webhook 时，流程如下：

Shopify 创建或更新客户
→ Shopify 发送 Customer Webhook
→ Webhook 中没有 Email Marketing Consent
→ Gadget 额外请求 Shopify
→ 获取 Email Marketing Consent
→ 将完整数据写入 Gadget

这种方式的优点是数据比较及时。

如果应用必须在收到 Webhook 后马上知道客户是否同意营销，就可以考虑使用 Fetch on Webhook。

Fetch on Webhook 的代价

Fetch on Webhook 会为每个相关 Webhook 产生额外数据获取。

如果店铺每天产生大量 Customer Webhook，就可能增加：

• Shopify API 请求。
• Gadget 平台用量。
• 数据同步压力。
• Webhook 处理时间。
• 应用运行成本。

如果应用并不需要实时使用这个字段，就没有必要在每一次 Webhook 发生时都获取它。

选择 Fetch Later

Fetch Later 的工作方式

将 Email Marketing Consent 的获取方式改为：

Fetch Later

这表示 Gadget 收到 Customer Webhook 时，不会立即请求这个字段。

Webhook 会先被正常处理，其他已经包含在 Webhook 中的数据仍然可以同步。

Email Marketing Consent 会在以下场景中获取：

• 夜间数据对账。
• 手动运行同步。
• Gadget 的数据同步流程。
• 其他配置好的完整数据刷新流程。

Fetch Later 的数据流程

使用 Fetch Later 后，流程变成：

Shopify 创建或更新客户
→ Shopify 发送 Customer Webhook
→ Gadget 保存 Webhook 中已有的数据
→ 不立即请求 Email Marketing Consent
→ 夜间对账或手动同步时获取
→ Gadget 补齐 Email Marketing Consent

这种方式适合不需要在 Webhook 到达的瞬间使用该字段的应用。

Fetch Later 的实际测试

创建一个新的 Shopify 客户，并允许接收营销邮件。

等待 Customer Webhook 进入 Gadget。

打开 Gadget 中的客户数据，可以看到：

• 客户记录已经创建。
• Webhook 中包含的字段已经同步。
• Email Marketing Consent 暂时没有数据。

这说明 Fetch Later 正在生效。

通过手动同步补齐数据

运行 Recent Data Sync

在 Gadget 的 Shopify 安装或数据同步页面，运行最近数据同步。

字幕中的操作类似于：

Sync recent data

同步开始后，Gadget 会从 Shopify 获取客户的更多字段。

之前为空的字段可能会被补齐，包括：

• Email Marketing Consent。
• 其他已添加但没有在 Webhook 中提供的客户字段。

检查同步结果

同步完成后，重新打开 Customer 数据。

确认：

• 客户记录仍然存在。
• Email Marketing Consent 已经出现。
• 客户其他需要同步的字段已经补齐。
• Webhook 没有被重复创建。
• 数据更新时间符合预期。

这个测试说明 Fetch Later 并不是永远不获取字段，而是将获取时间从 Webhook 实时处理阶段推迟到同步阶段。

移除不需要的字段

删除 SMS Marketing Consent

如果应用完全不使用 SMS Marketing Consent，可以从 Shopify Customer 模型中移除这个字段。

移除后，字段会回到可选的非 Webhook 字段列表中。

这样做适合以下情况：

• 应用不发送短信营销。
• 应用不需要判断短信同意状态。
• 应用只使用 Email Marketing Consent。
• 应用希望减少数据库字段。
• 应用希望减少不必要的数据同步。

以后重新添加字段

如果之后需要 SMS Marketing Consent，可以再次从非 Webhook 字段列表中将它添加回 Customer 模型。

添加后，再选择适合的同步方式：

• Fetch on Webhook。
• Fetch Later。

不要为了“以后可能会用”而默认添加所有字段。只添加当前业务确实需要的数据。

新建 Gadget 应用时的默认行为

非 Webhook 字段不会全部自动添加

如果是新的 Gadget Shopify 应用，非 Webhook 字段不会默认全部加入 Shopify 模型。

这些字段会显示在可选字段区域中，开发者可以按需添加。

这种设计有三个好处：

• 数据模型更干净。
• 避免不需要的 API 请求。
• 降低自动数据补齐带来的平台用量。

按业务用途选择字段

可以按照下面的原则选择字段：

客户营销同意数据的使用注意事项

Email Marketing Consent 不是普通标签

Email Marketing Consent 表示客户是否同意接收营销邮件。

应用不应该仅仅因为有客户邮箱，就向客户发送推广内容。

Shopify 官方说明，商家应只向明确同意接收营销内容的客户发送营销信息。客户可能通过以下方式订阅：

• 店铺 Newsletter 表单。
• 结账页面的邮箱营销勾选框。
• 客户账户登录流程中的营销选项。
• 其他 Shopify 支持的营销同意入口。

SMS Marketing Consent 需要单独处理

SMS Marketing Consent 与 Email Marketing Consent 是两种不同的营销权限。

客户同意邮件营销，不代表客户也同意短信营销。

应用需要分别检查：

Email Marketing Consent
SMS Marketing Consent

不能把一种同意状态当成另一种同意状态。

注意地区和隐私要求

营销同意的显示方式和法律要求可能因客户所在地不同而变化。

例如，某些地区可能需要双重确认，或者对短信营销有更严格的同意要求。

应用开发者应确保：

• 不向未同意的客户发送营销内容。
• 尊重客户撤回同意的状态。
• 根据当前 Shopify 数据更新客户权限。
• 按经营地区遵守适用的隐私和营销规则。
• 涉及法律判断时咨询专业人士。

Webhook 和同步策略的生产配置

需要实时数据时使用 Fetch on Webhook

如果应用收到 Customer Webhook 后，必须立即根据营销同意状态执行操作，可以使用 Fetch on Webhook。

例如：

客户更新营销同意
→ Webhook 到达
→ 立即获取完整同意状态
→ 更新营销系统标签
→ 触发客户分组逻辑

这种方案数据更新更快，但会增加额外请求。

不需要实时数据时使用 Fetch Later

如果应用只是每天生成营销客户列表，可以使用 Fetch Later。

例如：

白天接收 Customer Webhook
→ 暂时不获取非必要字段
→ 夜间统一同步客户数据
→ 第二天生成客户营销列表

这种方案更节省请求，也适合数据量较大的店铺。

完全不使用时移除字段

如果应用既不发送邮件，也不发送短信，就不需要添加对应的营销同意字段。

减少无用字段比添加后再忽略更好。

测试清单

升级和配置完成后，建议按以下顺序测试。

测试 Framework 升级

确认：

• Gadget Framework 已经升级到 1.6。
• 依赖安装成功。
• Shopify Customer 模型可以正常打开。
• Shopify Market 模型没有受到升级影响。
• 现有 Webhook 仍然可以接收。

测试 Fetch on Webhook

创建一个同意接收营销邮件的测试客户。

确认：

• Customer Webhook 成功进入 Gadget。
• 客户记录成功创建。
• Email Marketing Consent 在 Webhook 处理后出现。
• 日志中没有同步错误。

测试 Fetch Later

将 Email Marketing Consent 改为 Fetch Later。

再次创建一个测试客户。

确认：

• 客户记录可以创建。
• Webhook 处理时不会立即补齐该字段。
• Email Marketing Consent 暂时为空。
• 手动运行同步后字段出现。

测试字段移除

移除 SMS Marketing Consent。

确认：

• 该字段不再出现在 Customer 模型中。
• 字段回到可选列表。
• Customer Webhook 和同步仍然正常。
• 应用代码没有继续引用已经移除的字段。

这个功能适合什么类型的应用

Gadget Framework 1.6 的非 Webhook 字段配置适合以下应用：

• 邮件营销应用。
• 短信营销应用。
• 客户分群应用。
• 客户资料同步应用。
• CRM 集成应用。
• 客户数据仓库。
• 订单和客户分析工具。
• 多店铺数据同步应用。
• 需要控制 Shopify API 请求量的应用。

它尤其适合客户数据量较大的店铺，因为不是每个字段都需要在每一次 Webhook 发生时立即获取。

总结

这份字幕演示的是 Gadget Framework 1.6 对 Shopify 数据同步的改进。

核心功能是：

选择 Shopify 模型字段
→ 决定是否加入 Gadget
→ 决定 Webhook 时立即获取还是稍后获取

开发者可以为 Shopify Customer 模型中的非 Webhook 字段选择：

• Fetch on Webhook。
• Fetch Later。
• 不添加字段。

如果应用必须实时知道客户的营销同意状态，可以使用 Fetch on Webhook。

如果应用只需要定期同步或在营销活动前检查，可以使用 Fetch Later，让字段在夜间对账或手动同步时补齐。

如果应用完全不使用某个字段，则可以直接将它从模型中移除。

这个功能的实际价值不是让 Shopify Webhook 携带更多字段，而是让开发者更精确地控制数据同步时机，减少不必要的 Shopify API 请求、Gadget 平台用量和数据处理压力。

参考资料

citation:收集客户联系方式与营销同意

citation:结账页面中的营销订阅选项

citation:Shopify 客户隐私设置