> For the complete documentation index, see [llms.txt](https://helps.ptengine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helps.ptengine.com/cn/integrations/shopify.md).
# Shopify相关
> 关于Ptengine代码安装，请参阅[Shopify代码部署](/cn/start-guide/othertag/tag-shopify.md)。
## Shopify 整合设置指南
### 打开Shopify应用设置
请按照以下步骤操作进行Shopify集成：
1. 登录并访问相关账户
2. 在Experience模块下，点击档案列表右侧的“设置”图标，并点击“外部应用集成”，选择Shopify
3. 点击Shopify，进入后续设置
## 前往Shopify创建自定义应用
首先，您需要在Shopify中创建一个自定义应用，用于接收来自Ptengine的数据。 这个过程只需要不到5分钟的时间，无需技术技能（但需要您在Shopify中具有相关权限）。 这个自定义应用将仅在授权区域内运行，并且不会对您的商店性能或客户体验造成任何风险。
{% hint style="info" %}
Shopify已将自定义应用的创建入口迁移至 **Dev Dashboard**，并改为通过 **OAuth 授权**（Client ID + Secret）与Ptengine建立连接，不再使用「只显示一次的 Admin API 访问令牌」。
按旧流程创建的应用、以及Ptengine中已保存的连接仍然有效，无需重做；**新建**连接请按以下步骤操作。
{% endhint %}
创建自定义应用共分为五步：
1. 进入应用开发页面（Dev Dashboard）
2. 创建应用
3. 配置应用权限与回调地址
4. 安装应用
5. 获取 Client ID 与 Secret
### 第一步：进入应用开发页面（Dev Dashboard）
**方法一：从商店后台进入**
1. 进入Shopify商店后台管理页面，点击左下角「设置」
2. 点击「应用」，再点击右上角的「开发应用」
3. 点击「在 Dev Dashboard 中构建应用」
{% hint style="warning" %}
如果没有看到「在 Dev Dashboard 中构建应用」按钮，请点击旁边的「详细了解」，在新打开的页签中点击「Go to Dev Dashboard」。
如果提示没有权限，请更换为在该商店具有权限的账号（例如商店 Owner）后重试。
{% endhint %}
**方法二：直接访问 Dev Dashboard**
直接打开 ，并确认右上角显示的组织与目标商店一致。
### 第二步：创建应用
1. 在左侧选择「Apps」，点击右上角的「Create app」
2. 在右侧「Start from Dev Dashboard」中填写 App name（应用名称由您自行决定），点击「Create」
### 第三步：配置应用权限与回调地址
1. 在应用的「Versions」页面找到「Access」区块，点击 Scopes 右侧的「Select scopes」
新创建的应用默认没有任何权限，**必须完成本步骤的权限勾选**，否则无法接收Ptengine推送的数据。
2. 勾选 **Admin API** 下的 `read_customers` 与 `write_customers`
关闭弹窗后，Scopes 输入框中会显示 `read_customers,write_customers`。
3. 在「Redirect URLs」中填入以下地址，**必须完全一致**：
```
https://www.ptengine.com/shopify/oauth/callback
```
4. 确认无误后，点击右下角的「Release」发布该版本
权限与回调地址的改动只有在「Release」之后才会生效。
### 第四步：安装应用
1. 在应用的「Home」页面，点击右上角的「Install app」
2. 选择对应的商店，确认应用需要访问的权限后，点击「安装」
{% hint style="info" %}
安装时会提示「此应用尚未经过审核」，这是自定义应用的正常提示，可以继续安装。
{% endhint %}
### 第五步：获取 Client ID 与 Secret
在 中打开刚刚创建的应用，进入左侧「Settings」，在顶部「Credentials」区块获取 **Client ID** 与 **Secret**（点击右侧的复制图标即可复制）。
{% hint style="warning" %}
Secret 默认以密文显示，点击眼睛图标可以查看。
如果 Secret 泄露或丢失，可以点击「Rotate」重新生成。**重新生成后，Ptengine中已保存的连接需要同步更新，否则推送会失败。**
{% endhint %}
## 创建Shopify连接
### 创建Shopify连接
1. 在Ptengine的Shopify管理界面中，点击第二步中的“创建连接”
2. 在设置界面上输入相关信息
**链接名称**
请给这个连接起一个名字，便于在未来使用时识别
**Shopify商店名称**
注意，**这是您在Shopify中商店的注册信息，而非商店中的显示的名称**
您可以在Shopify后台的「设置 → 常规」中，商店名称的下方看到它（形如 `your-shop.myshopify.com`）
在登录Shopify后台的状态下，也可以直接从浏览器URL中看到它
或
**Client ID 与 Secret**
将上文「第五步：获取 Client ID 与 Secret」中复制的两个值，分别粘贴到对应的输入框
3. 信息均填写完成后，点击“OAuth”，在弹出的Shopify授权页面中确认授权
4. 授权成功后，连接就可以保存了。
如果您需要不同的表单结果推送至不同商店的用户列表，可以在这里创建多项连接。
#### 常见连接错误：
报错提示如上图，常见原因有：
* Shopify商店名称有误（须填写 `your-shop.myshopify.com` 中的注册名称，而非商店的显示名称）
* Client ID 或 Secret 有误，或应用中「Rotate」过 Secret 后未在Ptengine同步更新
* Shopify应用的「Redirect URLs」与上文给出的回调地址不完全一致
* 应用配置完成后未点击「Release」发布，或未在目标商店完成「Install app」
* 未勾选 `read_customers` / `write_customers` 权限
### 修改Shopify连接
点击列表后的编辑按钮，可以修改Shopify连接。
编辑的流程与创建的操作方式一致。
如果您由于Shopify中的设置发生变更（例如 Secret 经「Rotate」重新生成），可以在这里输入变更后的信息。
之前在体验中被设置过的连接会在修改后仍然保持生效。
### 删除Shopify连接
点击列表后的删除按钮，可以删除Shopify连接。
注意：设置在删除后无法恢复，请在删除前认真确认连接未来不再使用，以及不会影响使用该连接进行数据推送的体验。
在删除时，我们会为您检查运行中或定时中的体验，如果没有相关体验，您可以直接删除；但如果有正在运行或定时的体验，您需要勾选“确认”选框后，才能继续执行“删除”。
删除后，所有推送将立刻停止。
但对于体验本身的运行和表单数据在Ptengine中的收集，不会产生任何影响。
## 对体验设置Shopify推送
### 进入推送设置
请按照以下步骤操作，在体验中完成Shopify的推送设置
\*此设置仅适用于具备表单的体验，如果您无法看到相关选项，请先创建表单
1. 点击体验编辑
2. 查看“自动化”模块，点击“编辑”
（当前“自动化”仅具备表单结果推送功能，因此需要您在体验中先创建表单后才可查看。 未来将在此模块更新更多自动化能力，也欢迎您将数据推送、自动行为等自动化相关的需求反馈给我们。）
### 设置推送规则
1. 选择将结果推送至Shopify
2. 从之前创建好的连接中，选择需要使用的连接
3. 选择连接后，Ptengine将解析体验中所有使用到的表单字段
* 对于Email类型字段，Ptengine会自动识别与对应
* 对于其他类型字段，如果您需要推送，则需要手动添加、并指定它们与目标字段的匹配关系，例如：
* 关于Shopify必填字段
* Shopify使用”Email“字段作为唯一关联，因此在推送时，必须有对应推送Shopify Email的字段。
* 如果您创建了多个实验版本、或多个设备， 每个版本和设备的表单都必须有对应推送Shopify Email的字段。（默认情况下，Email会为您自动识别关联，但如果由于修改设置或其它异常导致失去关联，请您按照提示进行修正。）
1. 完成设置后，点击”保存“
2. 注意：推送设置只有”发布“或”更新发布“后，才会生效。
生效期间，表单收录到新提交数据时，数据将被实时推送至Shopify。
参考：当前支持Shopify接收的数据
| 字段 | 用途 | 备注 |
| ---------------- | ---------------- | ------------------------- |
| Email (Required) | 客户的邮箱地址，用于关联其它信息 | 作为唯一关联识别使用，必须确保设置时有对应关系 |
| First name | 客户名 | |
| Last name | 客户姓 | |
| Tag | 标签可用于对客户进行分组 | 可由表单字段映射，也可由「留资来源标记」设置固定值 |
| Subscription | 是否订阅 | 默认为订阅，暂时无法自定义 |
注意，当前综合Shopify的常用场景，由Ptengine收录并转发的Email，将自动标记为“客户同意接受营销电子邮件”，请酌情使用、并在需要的情况下于体验内容中告知用户。 未来我们将对此设置进行优化，支持该选项的自定义，以便适配更多邮箱收集场景。
### 设置留资来源标记
同一个 Shopify 店铺下如果有多个体验在收集留资，推送过去的客户档案默认无法区分「这个客户是从哪个活动来的」。开启「留资来源标记」后，可以为当前体验指定固定的标记，随每一次表单提交一起写入客户的 Tag。
1. 在「自动化」的推送设置中，完成连接与字段映射后，勾选「为本次留资的用户打上来源标记」
2. 点击「添加」，输入标记内容，按回车或点击 ✓ 确认
3. 需要多个标记时重复第 2 步；也可以用逗号分隔，一次输入多个
4. 点击「保存」，并在体验「发布」或「更新发布」后生效
设置限制：
| 项目 | 限制 |
| ------ | ------------ |
| 单个标记长度 | 最多 50 个字符 |
| 标记数量 | 每个体验最多 5 个 |
| 勾选该选项后 | 至少需要填写 1 个标记 |
{% hint style="warning" %}
**标记推送后无法由 Ptengine 撤回。**
取消勾选或删除标记，只影响之后的推送；已经写入 Shopify 客户档案的标记不会被移除。如需清理，请在 Shopify 后台的客户页面手动删除。
因此建议使用不会变更的活动标识（例如 `2026-spring-campaign`），不要使用日后可能改名的体验名称。
{% endhint %}
{% hint style="info" %}
**同一客户参加多个活动时，标记会累加。**
用同一个邮箱在多个体验中留资时，各体验的来源标记会依次追加到同一个客户档案上，不会互相覆盖，也不会替换该客户已有的其它标记。
{% endhint %}
**与「映射到 Tag 的表单字段」的区别**
| | 留资来源标记 | 映射到 Tag 的表单字段 |
| ------ | ------------ | ------------- |
| 值的来源 | 在设置中填写的固定值 | 用户在表单中填写的内容 |
| 每次提交的值 | 始终相同 | 可能不同 |
| 用途 | 记录留资来源（哪个活动） | 记录用户提交的内容 |
两者可以同时使用，互不影响。
{% hint style="info" %}
除来源标记外，由 Ptengine 推送的客户还会自动带上 `ptengine` 与 `customer_source=Ptengine` 两个固定标记，可用于在 Shopify 中筛选所有来自 Ptengine 的客户。
{% endhint %}
## 常见问题
### 在推送设置前或中断期间的数据，如何同步到Shopify中？
当前推送的工作时机是在有人提交表单、表单收录到数据时立刻实时推送。因此只在连接生效期间时工作，对于启用前、或失效期间的数据，即使表单数据能够收录在Ptengine的报告中，也无法在连接设置或恢复后自动推送至Shopify。
在这种情况下，可以通过手动下载Ptengine中的表格数据，并导入Shopify的顾客列表。
解决方法：
1. 在体验报告中，切换至”表单提交“，点击”CSV下载“
2. 前往Shopify，进入”客户“模块，点击右上角的”导入“
注意：请下载示例CSV，并将数据处理成对应格式后，进行上传。
### 对于已经订阅过的客户，Ptengine可以不展示相关体验吗？
Ptengine不限定邮箱用于”订阅“的场景，因此不会自动按照是否订阅来停止展示。
**对于Ptengine收集到的邮箱，可以通过限定”目标用户“来隐藏展示：**
1. 点击体验编辑
2. 查看“目标用户”模块，点击“编辑”
3. 切换至”触达特定条件的用户“，输入搜索”email“，并选中设置
将email条件设置为”空“，其含义为只在未收集到email的情况下展示体验。
这项设置可以与其它用户限定条件叠加使用，这样您可以实现更多样的个性化设置。
**对于已存在于Shopify客户列表中的邮箱，可以使用上述动作进行指定“邮箱排除”。**
注意，使用此功能需要：
Ptengine中设置过[User identification](https://help.ptengine.com/docs/ptx-user-identification/)（用户身份关联）
访问者需登录（否则无法建立起浏览环境与用户邮箱之间的关系）
1. 排除邮箱不超过1000个时
a. 打开email条件设置，选择“不包含”
b. 将需要排除的email直接黏贴进来（可批量），保存即可
2. 排除邮箱超过1000个时
需要通过其它技术方式对接，并需要贵方技术支持，如果需要请与我们联系。
Ptengine只能在是否展示体验层面进行控制，由于数据推送的特性，无法在用户提交邮箱后按照客户列表是否已存在进行验证报错。因此，如果您在提交成功后发放优惠券，如需限制优惠券的使用次数，请通过shopify后台设置，在结算步骤中校验。
