用 Gadget 开发 Shopify 商品问答推荐应用：从问卷配置到主题嵌入

商品问答推荐是一种很实用的 Shopify App。

顾客回答几个简单问题，应用根据答案推荐合适的商品。商家可以在后台创建问卷、设置问题和答案，再为每个答案绑定推荐商品。顾客完成问卷后，可以看到推荐结果并进入商品详情页。

本文使用 Gadget 的 Product Quiz 模板，结合 Shopify Theme App Extension，完成一个可以运行在店铺前台的商品问答应用。

最终流程如下：

商家在 Shopify Admin 创建问卷
        ↓
设置问题、答案和推荐商品
        ↓
问卷数据保存到 Gadget 数据库
        ↓
Theme App Extension 嵌入店铺主题
        ↓
顾客在店铺前台完成问卷
        ↓
应用根据答案计算推荐结果
        ↓
顾客查看推荐商品
        ↓
应用记录邮箱、答题结果和推荐商品

这个项目会用到什么技术？

项目由三部分组成。

Gadget 后台应用

Gadget 负责：

Shopify App 安装
OAuth
Shopify 商店连接
商品同步
数据库存储
问卷管理
推荐逻辑
结果记录
React 管理页面

Shopify Theme App Extension

Theme App Extension 负责：

将问卷显示在店铺前台
加载问卷数据
显示问题和选项
收集顾客回答
展示推荐商品
跳转到商品详情页

Shopify Online Store 主题

主题负责：

决定问卷显示在哪个页面
控制问卷区块的位置
让商家通过主题编辑器启用、移动和保存问卷

Shopify 支持通过 App Block 和 App Embed 将应用功能加入兼容的主题中。商家可以在主题编辑器里添加、移动、预览和保存应用区块。citation:Extend your theme with apps

使用 Gadget Product Quiz 模板

Gadget 提供了可以直接 Fork 的 Product Quiz 模板。

使用模板的好处是：

数据模型已经准备好
后端 Action 已经准备好
React 管理页面已经准备好
问卷表单逻辑已经准备好
问题和答案的关联关系已经准备好
商品推荐关系已经准备好
安装说明已经准备好

进入 Gadget 模板库，找到：

Product Quiz

点击：

Fork

然后填写新的 Gadget 应用名称，例如：

Product Quiz App

创建完成后，Gadget 通常会自动准备：

PostgreSQL 数据库
Node.js 后端
React 前端
商品问卷模型
后台 Action
前端页面
Shopify Connection 配置入口

使用模板并不代表应用已经完成。还需要连接 Shopify、安装应用、配置主题扩展并测试问卷流程。

连接 Shopify App

在 Gadget 项目中找到：

Connect to Shopify

如果还没有 Shopify App，需要先在 Shopify Dev Dashboard 中创建应用。

应用名称可以设置为：

Product Quiz App

创建后获取：

Client ID
Client Secret

将它们填写到 Gadget 的 Shopify Connection 中。

Client Secret 只能保存于：

Gadget 私密配置
服务端环境变量
密钥管理服务

不能放入：

店铺前台 JavaScript
Theme App Extension 的公开资源
GitHub 公开仓库
浏览器 Local Storage
HTML 页面

Shopify 当前以 Dev Dashboard 作为应用创建和管理中心。完整应用可以使用 Shopify CLI 创建，数据同步和后端集成也可以通过 Dev Dashboard 配置。citation:Building apps

配置商品数据和权限

Product Quiz 需要读取 Shopify 商品，通常需要：

read_products

还需要选择以下模型：

Shopify Product
Shopify Product Image
Shopify Shop
Shopify Theme
Shopify Asset
Shopify Sync
GDPR Request

其中：

Shopify Product 保存商品信息
Shopify Product Image 保存商品图片
Shopify Shop 保存商店连接
Shopify Theme 用于识别当前商店主题
Shopify Asset 用于处理主题相关资源
Shopify Sync 保存同步记录
GDPR Request 用于处理数据合规请求

如果应用只读取商品，不需要申请：

write_products

遵循最小权限原则可以让安装页面更容易理解，也能减少不必要的数据访问。

配置应用 URL 和 OAuth 回调地址

从 Gadget Shopify Connection 页面复制：

App URL
OAuth Callback URL

然后回到 Shopify App 配置中填写：

App URL
Allowed redirection URL

检查：

App URL 和 OAuth 回调地址没有填反
回调路径完整
使用 HTTPS
Development 和 Production 地址没有混用
Shopify Client ID 属于当前应用
保存并发布当前应用版本

配置错误时，常见结果包括：

安装后显示 Not Found
OAuth 无限跳转
Gadget 无法创建 Shop 记录
Embedded App 无法加载

安装到 Development Store

在 Shopify App 的安装页面选择一个 Development Store。

安装流程如下：

选择 Development Store
        ↓
查看应用权限
        ↓
点击安装
        ↓
完成 OAuth
        ↓
进入 Shopify Admin
        ↓
返回 Gadget 查看连接状态

安装完成后，Gadget 通常会生成当前商店的 Shop 记录。

Product Quiz 模板中的安装 Action 还可以在商店安装完成后自动发起商品同步。

进入 Gadget 的 Shopify Product 数据页面，检查商品是否已经出现。

如果商品数据已经存在，说明：

Shopify Connection 正常
read_products 生效
Shop 记录正常
自动同步 Action 正常
商品模型已经连接成功

理解 Product Quiz 的数据模型

Product Quiz 模板通常会包含以下业务模型：

Quiz
Question
Answer
Recommended Product
Quiz Result
Shopper Suggestion

这些模型之间的关系可以理解为：

Quiz
 ├── Question
 │    └── Answer
 │          └── Recommended Product
 └── Quiz Result
       └── Shopper Suggestion

Quiz

保存问卷本身的信息：

title
description
status
shopId

Question

保存问题内容和排序：

quizId
text
position

Answer

保存某个问题的选项：

questionId
text
position

Recommended Product

保存答案对应的推荐商品：

answerId
productId

Quiz Result

保存顾客完成问卷后的结果：

quizId
email
createdAt

Shopper Suggestion

保存这次答题推荐了哪些商品：

quizResultId
productId

实际字段名称以 Gadget 模板中的模型为准。

在 Gadget Admin 中创建第一份问卷

安装应用后，进入 Gadget 提供的 Embedded Admin 页面。

创建一份问卷。

例如：

Quiz title:
Which sweater is best for my dog?

Quiz description:
Take this quiz to find the best sweater for your best friend.

接着添加第一个问题：

Question:
Is your dog long?

添加两个答案：

Yes
No

分别为答案绑定推荐商品：

Yes → Party Animal
No  → Autumn Breeze

继续添加第二个问题：

Question:
Does your dog like the festive spirit?

添加答案：

Yes → Santa's Little Helper
No  → Amora Fine the Gentleman

保存问卷后，Gadget 会创建：

一条 Quiz 记录
多条 Question 记录
多条 Answer 记录
推荐商品关联记录

进入 Gadget Data 页面，可以检查这些数据是否已经保存。

商品推荐逻辑

问卷推荐逻辑可以理解为：

顾客选择答案
        ↓
读取答案对应的推荐商品
        ↓
合并所有推荐商品
        ↓
去除重复商品
        ↓
显示最终推荐结果

例如：

问题一选择 Yes
问题二选择 No
        ↓
Party Animal
Amora Fine the Gentleman

如果多个答案推荐同一个商品，前端应该只显示一次。

生产应用还可以增加：

推荐权重
商品优先级
最多显示几个商品
商品缺货时自动隐藏
商品下架时自动替换
按顾客地区推荐
按价格区间推荐

创建 Theme App Extension

问卷要显示在店铺前台，需要使用 Theme App Extension。

Theme App Extension 的作用是：

将应用功能作为主题区块
添加到 Online Store 2.0 主题中

通常需要使用 Shopify CLI 创建或下载包含 Theme Extension 的项目。

如果 Gadget 模板的安装页面提供了 Theme App Extension 项目地址，优先使用该项目，因为其中通常已经包含：

extensions/
assets/
blocks/
shopify.extension.toml

Theme Extension 中通常包含两个关键部分：

assets/product-quiz.js
blocks/quiz-page.liquid

`quiz-page.liquid`

这个文件负责：

显示问卷容器
读取主题区块设置
输出问卷 ID
加载 JavaScript
为商家提供主题编辑器设置项

`product-quiz.js`

这个文件负责：

请求 Gadget 后端
获取问卷数据
显示问题和答案
记录顾客选择
提交邮箱
显示推荐结果
跳转商品详情页

Theme Extension 的公开 JavaScript 中不能放：

Client Secret
Access Token
数据库密码
第三方私钥

安装 Theme Extension 项目依赖

进入 Theme App Extension 项目目录后，安装依赖：

yarn

或者使用当前项目所配置的包管理命令。

然后打开项目查看结构。

如果这是一个 Extension-only Shopify CLI 项目，通常不需要 Remix，因为：

Gadget 提供后台和管理页面
Theme Extension 只负责店铺前台

配置 Gadget API 地址

Theme Extension 的前端 JavaScript 需要请求 Gadget 后端。

在 quiz-page.liquid 或对应的主题区块文件中，需要加载 Gadget 项目的公开 API 地址。

通常可以从 Gadget 的 API 文档或安装说明中获取对应的 Script URL。

这个地址可以公开，但必须注意：

只暴露公开 API
不暴露 Client Secret
不暴露 Access Token
服务端仍然要验证请求参数
不能让前端任意读取其他商店数据

如果 Gadget 模板提供了专用的 Script Tag，优先使用模板中提供的地址，不要手动拼接域名。

配置 Quiz ID

一份 Gadget 问卷创建后，会生成一个 Quiz ID。

例如：

quiz_id: quiz_123456

在主题扩展设置中，将 Quiz ID 填入：

Quiz slug
Quiz ID

具体字段名称以模板的主题区块设置为准。

前台加载流程如下：

读取主题区块中的 Quiz ID
        ↓
请求 Gadget API
        ↓
获取 Quiz、Question 和 Answer
        ↓
渲染问卷

如果没有配置 Quiz ID，前台可以显示提示：

Please select a quiz in the app settings.

不要让前台因为缺少 Quiz ID 而显示空白或 JavaScript 报错。

启动 Theme Extension 开发预览

使用 Shopify CLI 启动开发预览。

常见命令可能是：

shopify app dev

或者项目中提供的：

yarn dev

启动过程中：

选择 Shopify Partners 组织
选择已经连接 Gadget 的 Shopify App
选择同一个 Development Store
启动 Theme Extension 预览
打开主题编辑器
添加 Quiz App Block
选择 Quiz ID
保存主题

一定要选择和 Gadget Shopify Connection 使用的同一个 Shopify App。

如果选择了另一个 App，可能出现：

Extension 没有显示
Gadget 与主题扩展使用不同应用
API 地址不一致
主题区块安装成功但问卷无法加载

在 Shopify 主题编辑器中添加问卷

如果商店使用 Online Store 2.0 主题，可以进入：

Online Store → Themes → Customize

然后：

选择要显示问卷的页面
点击 Add section 或 Add block
在 Apps 中选择 Product Quiz
将区块拖到合适位置
在设置中填入 Quiz ID
点击 Save

Shopify 官方支持在主题编辑器中添加、移动、预览和保存 App Block。更换已发布主题后，应用区块通常需要在新主题中重新激活。citation:Extend your theme with apps

Online Store 2.0 与旧主题

Theme App Extension 最适合 Online Store 2.0 主题。

如果主题支持 App Block，商家可以通过主题编辑器完成安装，不需要手动修改 Liquid 文件。

如果主题是较旧的 Online Store 1.0 主题，通常需要：

手动复制 Liquid 代码
手动复制 JavaScript 文件
手动添加 Script Tag
手动配置数据属性
处理主题结构差异

旧主题的安装方式更容易受到主题结构影响。

因此，生产应用最好：

优先支持 Online Store 2.0
在安装页面检测主题版本
为旧主题提供单独说明
给商家提供必要的代码片段
明确提示备份主题

Product Quiz 模板可以根据商店主题信息显示不同的安装指导。主题和资源模型通常用于判断当前商店使用的主题类型。

部署 Theme App Extension

开发完成后，使用 Shopify CLI 发布 Theme Extension。

通常流程如下：

构建 Extension
        ↓
运行部署命令
        ↓
选择正确 Shopify App
        ↓
创建新的 App Version
        ↓
发布版本

部分项目会使用：

shopify app deploy

具体命令以当前 Shopify CLI 项目输出为准。

Shopify 会托管 Theme App Extension 的资源，开发者不需要单独准备静态资源服务器。

部署完成后：

回到 Gadget Admin
打开安装页面
选择目标主题
点击 Preview 或 Add to theme
将 Quiz ID 填入主题区块设置
保存主题
打开店铺前台测试

在前台测试问卷

可以使用以下测试问卷：

Question 1:
Is your dog long?

Answer:
Yes

Question 2:
Does your dog like the festive spirit?

Answer:
No

提交邮箱：

test@example.com

预期结果：

显示 Party Animal
显示 Amora Fine the Gentleman

点击商品按钮后，应跳转到对应商品详情页。

然后回到 Gadget Data 页面，检查：

Quiz Result 是否创建
顾客邮箱是否保存
Shopper Suggestion 是否创建
推荐商品是否正确
答题时间是否记录

处理未登录顾客的权限

店铺前台的顾客通常没有登录 Shopify Admin，也不是 Gadget 的后台用户。

因此，问卷前台需要使用公开访问能力，但公开 API 必须非常谨慎。

前台可以开放：

读取公开问卷
读取公开问题
读取公开答案
读取必要的商品信息
创建 Quiz Result
创建 Shopper Suggestion

不应该开放：

读取所有商店设置
读取其他商店的问卷
读取 Access Token
修改任意商品
读取订单和客户后台数据

公开请求还需要处理：

输入校验
频率限制
垃圾提交
重复提交
恶意邮箱
超长文本
非法 Quiz ID
跨商店数据访问

如果应用收集顾客邮箱，需要明确说明用途，并根据业务地区配置隐私政策、Cookie 和数据处理规则。Shopify 提供顾客隐私设置、隐私政策和 Cookie Banner 等工具，但具体合规要求应结合业务所在地确认。citation:Understanding customer privacy settings

保存顾客邮箱和答题结果

当顾客完成问卷并提交邮箱时，应用可以保存：

email
quizId
answers
recommendedProducts
createdAt
shopId

建议只保存业务真正需要的数据。

如果只是为了发送推荐结果，可以不保存：

不必要的完整浏览记录
与推荐无关的个人信息
不需要长期保存的原始输入
过多的设备信息

应用还应该准备：

隐私政策链接
数据删除流程
顾客数据访问流程
数据保留时间
取消营销订阅的处理方式

如果应用未来提交 Shopify App Store，还需要提前规划应用审核和数据合规要求。

理解 Product Quiz 模板的后端结构

Product Quiz 模板中最重要的后端逻辑通常包括：

Shop 安装 Action

商店安装应用后：

创建 Shop 记录
保存商店连接
启动商品同步
初始化应用数据

Quiz Delete Action

删除 Quiz 时，执行级联删除：

删除 Quiz
        ↓
删除 Questions
        ↓
删除 Answers
        ↓
删除推荐商品关系

这样可以避免数据库中留下孤立数据。

Quiz Update Action

保存问卷标题、描述、问题和答案。

Quiz Result Action

记录顾客完成问卷后的结果。

Shopper Suggestion Action

记录推荐给顾客的商品。

理解 Product Quiz 模板的前端结构

模板前端通常包含：

Pages
├── Homepage
├── Create Quiz
├── Edit Quiz
└── Install

常见组件包括：

QuizForm
QuestionForm
AnswerForm
RecommendedProductSelector

表单可以使用 Gadget 提供的 useActionForm 或类似表单 Hook。

它可以帮助处理：

表单状态
嵌套问题
多个答案
表单提交
加载状态
错误状态
Action 调用

安装页面则负责：

检测主题版本
显示 Online Store 2.0 安装方法
显示旧主题安装方法
生成主题扩展设置
提供 Quiz ID
指导商家完成主题配置

生产环境部署

Development 测试完成后，再部署 Production。

生产环境建议使用独立的：

Shopify Production App
Gadget Production 环境
Client ID
Client Secret
数据库
环境变量
Theme App Extension 版本

部署顺序如下：

Development 测试
        ↓
发布 Shopify Theme App Extension
        ↓
部署 Gadget Production
        ↓
配置生产应用地址
        ↓
安装到目标商店
        ↓
选择生产主题
        ↓
添加 Quiz App Block
        ↓
填入生产 Quiz ID
        ↓
完成真实前台测试

生产环境中需要确认：

商品同步正常
问卷管理页面正常
主题区块正常显示
顾客可以完成问卷
推荐商品链接正确
Quiz Result 可以保存
顾客邮箱保存符合隐私要求
Development 和 Production 数据没有混用

常见问题排查

Gadget Admin 可以打开，但前台问卷没有显示

检查：

Theme App Extension 是否已经部署
主题是否支持 App Block
Quiz ID 是否正确
主题编辑器中是否已经添加区块
JavaScript 是否加载成功
Gadget API 地址是否正确
当前查看的是正确店铺

主题编辑器找不到 Quiz App Block

检查：

当前主题是否支持 Online Store 2.0
Extension 是否已安装
Extension 是否发布到了正确的 Shopify App
当前商店是否安装了对应应用
是否选择了错误的主题或开发商店

问卷显示但没有问题

检查：

Quiz ID 是否正确
Gadget 中是否有 Question 记录
Question 是否关联到当前 Quiz
API 是否返回数据
前台请求是否被权限控制拒绝
浏览器 Console 是否有 JavaScript 错误

顾客提交邮箱后没有结果

检查：

Quiz Result Action 是否有公开访问权限
Shopper Suggestion 是否可以创建
邮箱格式是否通过校验
后端是否拒绝了请求
Gadget 日志中是否有错误
是否触发了请求频率限制

旧主题安装失败

检查：

是否按照旧主题安装说明复制了文件
Liquid 文件位置是否正确
Script Tag 是否加载
主题中是否存在冲突的 JavaScript
是否已经备份主题
是否可以优先迁移到 Online Store 2.0 主题

顾客可以读取不属于自己的数据

这是安全问题，需要立即处理。

检查：

公开 API 是否按 shopId 过滤
Quiz ID 是否绑定当前商店
前端是否可以修改 shopId
后端是否验证了问卷所属商店
是否把内部数据库 API 直接暴露到了前台

项目验收清单

完成以下检查后，商品问答应用才算真正跑通：

Gadget Product Quiz 模板创建成功
Shopify App 可以安装
OAuth 流程正常
Shop 记录成功创建
商品数据同步成功
商品图片可以读取
Quiz 可以创建
Question 可以创建
Answer 可以创建
Answer 可以绑定推荐商品
Quiz 可以编辑和删除
删除 Quiz 时关联数据可以清理
Theme App Extension 成功创建
Online Store 2.0 主题可以添加 Quiz Block
Quiz ID 可以正确配置
店铺前台可以加载问卷
顾客可以完成答题
推荐商品显示正确
商品链接可以正常跳转
Quiz Result 可以保存
Shopper Suggestion 可以保存
顾客邮箱经过合理处理
公开 API 没有暴露后台敏感数据
Development 和 Production 环境彼此隔离

结语

这个 Product Quiz 应用完整展示了 Shopify 店铺前台应用的一条开发链路：

Fork Gadget 模板
        ↓
连接 Shopify
        ↓
同步商品数据
        ↓
在 Gadget Admin 创建问卷
        ↓
配置问题、答案和推荐商品
        ↓
创建 Theme App Extension
        ↓
连接 Gadget API
        ↓
将 Quiz Block 加入 Shopify 主题
        ↓
顾客完成问卷
        ↓
显示推荐商品
        ↓
保存答题结果和邮箱
        ↓
部署到 Production

Gadget 主要负责：

数据库
后端服务
商品同步
问卷管理
推荐关系
顾客结果
Admin 页面
Action 和权限

Shopify 主要负责：

应用安装
商品和商店数据
Theme App Extension
Online Store 主题编辑器
App Block
店铺前台展示
商品详情页跳转

开发者真正需要设计的是：

问题和答案的业务关系
答案如何对应推荐商品
推荐商品如何去重
顾客数据保存多久
前台公开 API 如何保护
Online Store 2.0 和旧主题如何兼容
如何处理商品下架和缺货
如何让商家能够独立创建和管理问卷

当这个商品问答应用运行起来后，还可以继续扩展：

根据顾客预算推荐商品
根据颜色、尺寸和用途推荐商品
支持多个问卷
支持不同页面显示不同问卷
增加商品库存判断
推荐商品加入购物车
发送邮件推荐结果
统计问题完成率
统计推荐商品点击率
使用 AI 自动生成问题和答案
根据历史答题数据优化推荐规则

citation:Extend your theme with apps

citation:Building apps

citation:Understanding customer privacy settings

文章目录