Help: integrations

把页面发布到 Shopify

按顺序完成专用应用准备、店铺连接、页面添加、更新和下线。

开始前确认应用与店铺

准备好目标工作区的应用创建与配置负责人、适用的安装 ZIP，以及能在 Shopify 配置和安装应用的负责人。还需核对店铺所属组织、允许安装的店铺范围与连接用应用的条件是否匹配。

推送本身会把页面在 Shopify 上线，先确认目标店铺、页面内容和发布负责人。使用有效预览链接时，不必先在 Ptengine AI 用独立域名发布。下面按一次一页的手动推送流程操作。

向接入负责人取得适用于当前环境的 ZIP，以及该版本对应的 Shopify 连接配置说明。不要仅凭文件名判断是否为最新版或已经适配。
打开“探索应用 → 自定义应用管理 → 新建”，填写应用名并选择 ZIP。按Custom App 开发与发布指南中的 schema 分支完成创建、上传和部署。
在应用详情“基本信息”查看应用地址。由 Shopify 负责人在 Dev Dashboard 按“Apps → Create app → Start from Dev Dashboard”创建并命名连接用应用；已有应用时打开其详情。在 Versions 配置所用版本需要的 URL 和权限后 Release，再到 App settings 查看 Client ID 与 Client secret。界面细节可参照Shopify 官方创建流程。
采用客户端 ID 与密钥连接的版本，将 SHOPIFY_CLIENT_ID 保存到“配置”，将 SHOPIFY_CLIENT_SECRET 保存到“密钥”；负责人应核对与安装包声明一致。
配置变更后，在“版本”对目标版本执行“重新部署”，确认成功和发布状态后再打开应用。仅刷新浏览器不能代替配置生效检查。

没有 ZIP 或连接配置说明时，把工作区名称和目标 Shopify 店铺交给接入负责人准备。已经配置好的环境，可从下一步开始。

采用客户端 ID / 密钥的专用包，可按以下连接配置核对。设置前应由接入负责人确认与所用版本说明一致。“应用地址”替换成目标应用实际的 HTTPS 地址。

配置项	值
App URL	应用地址 + `/api/shopify/install`
Redirect URL	应用地址 + `/api/shopify/oauth/callback`
Scopes	`read_online_store_pages,write_online_store_pages,read_themes`
在 Shopify 后台嵌入应用	此连接方式关闭嵌入。

不要混用其他连接方式、其他应用或旧环境的 URL。修改 Shopify 权限后，店铺可能还需要重新确认授权。

打开专用应用，在店铺地址栏填写 your-store.myshopify.com 等 Shopify 店铺地址并连接。不要混淆独立前台域名与 Shopify 授权店铺。
在新开的 Shopify 窗口核对目标店铺和请求权限，确认后安装授权；没有权限时，请店主或有安装权限的人处理。
看到连接完成提示后关闭窗口，回到 Ptengine 确认已连接状态及店铺名称。
有多家店铺时，在上方店铺选择框明确选择本次推送目标，不能默认使用第一家。

如果所用版本从 Shopify 后台打开时会显示连接码，可在 Ptengine 应用选择“用连接码连接”，填入所显示的代码。无效、已使用或过期时，回 Shopify 重新获取；有效期按当前画面提示确认。

准备来源：已发布页面复制公开 URL；未发布页面在编辑器点击“预览”，再用预览页的“复制链接”取得完整链接。不能使用需要登录才能打开的编辑器地址。
在专用应用点击“添加页面”，粘贴 URL 后点击“下一步”。所用版本若能分别填写 PC 和手机来源，请分别选择对应链接。
填写店铺 /pages/ 下的路径，查看允许字符和占用检查。若已有其他页面使用该路径，换成未占用路径。
选择页面模板，以及是否“加上店铺的头部和页脚”。源页面自带导航不会自动删除，勾选前检查是否会出现两层导航。
所用版本若提供“页面访问域名”，请选择实际使用的前台域名；需要手动填写独立前台域名时，也要检查显示的最终 URL。此选项不会替你修改 DNS 或店铺的前台承载配置。
核对店铺、最终 URL、显示方式和内容后点击“推送”，确认成功并在列表中找到该页面。

内容更新与修改路径、模板等设置是不同操作。源页面修改不会自动同步到 Shopify；本指南按单页手动推送，不据此承诺批量推送或自动同步。

修改路径、显示方式或模板时，在列表行末打开 ··· → 编辑。
修改后点击“保存并推送”。这一步会重新读取源页面内容，也要核对是否包含未计划同步的修改；要求补充预览链接时使用新链接。
修改网址后打开新 URL，并检查广告、链接、二维码等引用是否需要更新，不假设旧 URL 会自动跳转。
需要下线时，选择行末菜单的“下线”，核对确认框中的店铺、页面名和 URL。这会删除 Shopify 中的目标页面，执行前保留以后重用的来源；完成后检查列表和原公开 URL。

“断开”店铺连接是另一项操作。断开后不能再通过该连接推送，但不会批量删除已经在 Shopify 创建的页面。

现象	处理
无法读取来源	检查是否误用登录后编辑器 URL，预览链接是否完整有效；过期则重新获取。
路径已占用	核对目标店铺和路径，换成未占用路径，不用此流程覆盖无关的既有页面。
连接失败或授权失效	由负责人检查连接配置与重新部署结果；在 Shopify 卸载过应用等情况下，需要重新连接授权。
页面代码超过大小上限	按画面提示精简无用区块和内嵌数据；区分外部引用图片与直接嵌入代码的数据。
公开地址的域名不对	核对目标店铺和保存的页面访问域名；API 授权店铺域名可能不同于实际前台域名。
页面可打开但没有访问数据	确认公开店铺域名已纳入 Ptengine 计测范围，并检查所需标签是否工作。

不要在主题与页面中重复加入同一档案的标签。按安装检查验证真实请求与数据。仍有问题时，向接入负责人提供应用版本、店铺、来源类型、操作和错误信息。