通过本店密钥提交的评论会进入 Shopify 后台的 Customerssay 应用 → Manage Reviews,并遵循店铺的审核与发布设置。待审核评论批准后才会公开显示。
一 开始前需要准备什么
准备已安装正式应用的 Shopify 店铺、可部署的自建店面,以及店面的完整域名。二 创建 API 密钥
打开 Shopify 后台 → 应用 → Customerssay.ai Reviews App → Headless。左侧 Create public key 用于浏览器,右侧 Create secret key 用于服务端。
图 1 进入 Headless 页面后 在对应区域创建密钥
创建浏览器公钥
- 在 Create public key 的 Name 中输入容易识别的名称,例如 My Headless Storefront。
- 在 Allowed origins 中填写真实店面域名,每行一个。示例
https://shop.example.com和https://www.shop.example.com;上线时替换为你的域名。 - 点击 Create public key,复制以 pk_live_ 开头的完整公钥。已有公钥可在列表中点击 Copy。
- 把公钥放入浏览器接入配置;测试域名和正式域名需要分别登记。
https://shop.example.com 与 https://www.shop.example.com 不相同;http://localhost:3000 与 http://localhost:5173 也不相同。生产使用 HTTPS,本地开发可以登记 http://localhost:端口。最多登记 20 个 Origin。
创建服务端私钥
- 只有服务端读取、代提交或 SSR 接入才需要私钥。在 Create secret key 中填写名称,例如 Storefront Server。
- 点击 Create secret key,立即复制以 sk_live_ 开头的完整私钥。私钥明文只显示一次。
- 保存到服务端环境变量或部署平台的 Secret 设置,完成后重新部署服务端。不要放入浏览器配置、HTML、截图或公开仓库。
三 配置自建店面链接
需要 Google Shopping Feed 的商品链接跳转到自建站时,在 Headless settings 勾选 Enable headless mode,填写 Storefront base URL,例如https://shop.example.com,再填写 Product URL template,例如 /products/{handle},最后点击 Save settings。这个设置控制链接目标;API 接入仍通过密钥鉴权。

图 2 自建店面地址 商品路径模板和邀评邮件链接设置
{handle};例如 /en-us/products/{handle}。
如果店铺没有 Online Store 渠道,或主题商店受密码保护,将 Review request email links 选择为 App-hosted pages,再保存。邀评和退订链接将使用应用托管页面;普通主题商店可继续使用默认 App Proxy。
四 选择适合的接入方式
正式 API 基础地址为
https://app-next.customerssay.ai/api/storefront/v1。下面先给最快的 JS 接入,再给自定义 API 与服务端方案。
五 使用自带 JS 评论组件
将以下内容加入商品页。替换公钥、YOUR_STORE.myshopify.com 和 YOUR_PRODUCT_ID;商品 ID 应来自该店铺真实商品,可使用纯数字或 Shopify Product GID。配置脚本需要在 embed.js 之前执行。- 把页面部署到已登记的 Origin。直接双击本地 HTML 文件的 file:// 页面不能作为正式测试域名。
- 打开真实商品页,确认评论区、星级与写评论入口出现。没有已发布评论时会显示空状态。
- 提交一条明确标注为测试的评论,到应用 Manage Reviews 中检查是否收到,并按店铺审核设置发布。
window.CustomersSay.mount(element, { productId }) 挂载新商品。不要保留旧商品的评论实例。
有内容安全策略 CSP 的站点,需要允许应用域名加载脚本、样式并发起请求,允许媒体域名加载图片和视频。配置脚本按框架添加实际 nonce;现成组件还需要 style-src-attr 的内联样式许可。Swiper 资源由应用域名提供。
六 使用 API 和自己的样式
评论展示和提交可以分开实现。以下代码用于浏览器,请从已登记域名运行。将读取和提交示例放在同一个前端 ES 模块文件中,或同一个<script type="module"> 中,以支持顶层 await 和共享配置。先在页面放入 <ul id="review-list"></ul>,再执行读取代码。返回值中的 summary.total_reviews 和 summary.average_rating 可用于你自己的评分摘要。
提交评论
商品评论提交使用 FormData,不是 JSON。不要手工设置 Content-Type,浏览器会生成 multipart boundary。必填项以店铺表单设置为准;评分必须为 1 到 5 的整数。上传图片或视频
- 用 FormData 向 POST /media-upload?productId=YOUR_PRODUCT_ID 上传 file 和 type(image 或 video),请求带 X-CustomersSay-Key。
- 从响应 file 中读取 url、type、thumbnailUrl 和 tempId;同一条评论的后续文件沿用 tempId。
- 提交评论时,把预上传结果依次加入 mediaUrls[]、mediaTypes[]、mediaThumbnails[]。图片的 thumbnailUrl 为空时传空字符串,保持数组顺序一致。
七 在服务端接入和渲染首屏
在 Hydrogen 的服务端 loader、Next.js 服务端路由或其他后端中调用 API。私钥只从服务端 Secret 读取,不要放入 PUBLIC 或 NEXT_PUBLIC 变量,也不要作为 loader 返回值或组件 prop 返回给浏览器。下面是可放入 .server.js 模块的通用辅助函数。八 常用接口与错误排查
当前基础限流按密钥和访客 IP 区分:读 120 次每分钟,写 20 次每分钟,各业务接口还有单独限制。私钥 SSR 若不转发可信访客 IP,会让访客共用服务端出口 IP 的额度。请求超时、5xx 或 429 时展示可恢复的错误;不要将读取失败展示为“0 条评论”。
九 更换密钥与上线验收
- 先创建新密钥并登记正式域名,更新前端或服务端配置,部署并确认读写成功。
- 回到 API keys,对旧公钥可使用 Edit origins 调整允许域名;停用旧密钥时点击 Revoke 并确认。私钥遗失时创建新密钥。
- 撤销后旧密钥立即不可用;应用卸载后原密钥也会失效,重装应用后需要重新创建并更新配置。
- 用真实正式域名检查桌面和手机评论区,确认不会横向溢出。
- 检查空评论 多页数据 1 到 5 星筛选以及审核未发布状态。
- 验证一次评论和图片上传,保留或清理测试样例。
- 检查页面源码与浏览器网络请求,确保没有 sk_live_ 私钥。
- 验证更换密钥后新配置可用,并对 403 429 和服务故障显示明确提示。