> 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/start-guide/othertag/tag-shopify-app.md).
# Ptengine for Shopify 应用安装
Ptengine for Shopify 是 Ptengine 为 Shopify 平台开发的专用应用，符合 Shopify 的平台安全规范。安装后会自动完成基础代码部署，并自动采集加购、结账、支付完成等关键行为事件（详见下方“应用自动采集的事件”）。Ptengine 基于这些数据帮您更快洞察访客在商店中的行为，并通过 A/B 测试、弹窗等个性化工具快速验证优化假设，提升页面表现。
Shopify 商店可以通过以下两种方式部署 Ptengine，本文介绍方式一：
| 部署方式 | 适合谁 | 说明 |
| ----------------------------------------------------- | -------------------------------- | ---------------------------------------------- |
| 方式一：安装 Ptengine for Shopify 应用（推荐，本文） | 使用 Shopify 在线商店主题的商店 | 在 Shopify 应用商店安装后自动部署基础代码，并自动采集关键行为事件，无需改动主题代码 |
| 方式二：[手动部署代码](/cn/start-guide/othertag/tag-shopify.md) | 无法安装应用，或需要在访客拒绝 Cookie 后仍采集数据的商店 | 在 theme.liquid 中粘贴基础代码，并在“客户事件”中添加自定义像素事件代码 |
{% hint style="warning" %}
无头（Headless）商店，例如使用 Hydrogen 或自建前端的商店，没有 Shopify 主题，无法通过应用嵌入部署，暂不适用本文的安装方式。请联系我们获取对应的部署方案。
{% endhint %}
## 安装前的准备
安装后 Ptengine 会根据商店域名和 Shopify 主账号自动判断是连接已有档案还是创建新档案（详见第二步）。为顺利完成安装，请先确认以下事项：
* **Shopify 主账号的权限**：连接已有档案时，主账号（店主）邮箱需要在该 Ptengine 档案中拥有【创建者】或【管理员】权限。确认方法见下方常见问题“如何确认 Shopify 主账号”和“如何确认 Ptengine 档案内的权限”。
* **删除手动部署的旧代码**：如果商店之前手动部署过 Ptengine 的基础代码和事件代码，请在安装前先删除，否则会与应用自动采集的事件重复。方法见下方常见问题“如何删除已有的基础代码和事件代码”。
* **邮箱**：为便于管理，建议同一家公司的 Ptengine 管理者使用同一个邮箱。主账号邮箱还没有 Ptengine 账号时，安装过程中会自动创建。
## 安装流程
### 第一步：在 Shopify 应用商店安装应用并确认权限
在 Shopify 应用商店搜索“Ptengine”，进入应用页面点击“Install”。
跳转到商店后台后，确认应用所需的数据权限，再次点击“Install”完成安装。
### 第二步：连接或创建档案
安装完成后会自动跳转到 Ptengine。Ptengine 会根据商店域名和 Shopify 主账号自动判断，进入以下四种情况之一：
| 情况 | Ptengine 检测到的状态 | 页面显示 | 您需要做的 |
| ---------- | -------------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| 1. 连接已有档案 | 商店域名对应的档案已经部署过代码并有数据，且主账号在该档案拥有【创建者】或【管理员】权限 | “连接已有档案”，显示商店域名和档案名 | 点击“现在连接”。Ptengine 会为该档案重新部署基础代码和事件代码，然后进入第三步 |
| 2. 需要权限 | 商店域名对应的档案已经部署过代码并有数据，但主账号在该档案没有【创建者】或【管理员】权限 | “连接档案需要权限”，提示需要调整权限的账号邮箱 | 点击“了解”关闭页面。请该档案的创建者或管理员先把这个邮箱的权限调整为【管理员】（见常见问题“如何确认 Ptengine 档案内的权限”），再在 Shopify 后台“应用”中重新打开 Ptengine |
| 3. 选择档案 | 商店尚未部署代码，但主账号下已有自己拥有【创建者】或【管理员】权限的档案 | “连接已有档案”，带档案下拉框 | 在下拉框中选择要连接的档案，点击“确认”；如果都不合适，点击“创建新的档案”。之后进入第三步 |
| 4. 自动创建新档案 | 主账号邮箱还没有 Ptengine 账号，或账号下没有自己管理的档案 | 直接进入“安装代码”页 | Ptengine 已自动用主账号邮箱创建账号和新档案，直接进入第三步 |
情况 1 的页面：
情况 2 的页面：
情况 3 的页面：
{% hint style="info" %}
为保障数据安全，只有档案的【创建者】或【管理员】可以连接数据。情况 1 和情况 3 连接前，如果商店之前手动部署过 Ptengine 代码，请先按常见问题“如何删除已有的基础代码和事件代码”删除，避免重复采集。
{% endhint %}
### 第三步：复制安装代码
进入“安装代码”页面，点击“复制代码”复制基础代码。
### 第四步：前往 Shopify 主题编辑器粘贴代码
点击“去 Shopify 安装”，会打开 Shopify 主题编辑器的“应用嵌入”面板。确认 Ptengine 的 App Embed 开关已打开，把刚复制的代码粘贴到“Tag Installation”输入框，然后点击右上角“保存”。
### 第五步：验证安装是否成功
回到 Ptengine 的“安装代码”页面，在第 3 步输入商店任意页面的 URL，点击“检查”。提示“成功检测到代码”即表示安装完成，点击“进入 Ptengine”开始使用。安装了基础代码的页面被访问后，数据大约在 30 分钟后显示。
## 安装后的使用方法与注意事项
安装后，在 Shopify 后台左侧菜单点击“应用”，在已安装的应用中找到 Ptengine 即可进入。
{% hint style="info" %}
Shopify 中应用的使用权限由主账号分享给其他成员，因此从 Shopify 后台进入 Ptengine 时，一律以主账号身份登录。团队成员也可以用各自的 Ptengine 账号直接访问 ptengine.com 使用。
如果主账号之前没有创建过 Ptengine 账号，安装应用后请先设置账号密码，方法见下方常见问题“如何设置 Ptengine 账号密码”。
{% endhint %}
{% hint style="warning" %}
Ptengine for Shopify 以应用嵌入（App Embed）的形式安装在当前主题中。**更换主题后 Ptengine 的监测会失效**，请在更换主题前联系我们，以确保数据统计不受影响。
{% endhint %}
## 应用自动采集的事件
安装应用后，以下事件会自动采集，无需再手动部署事件代码。
| 事件名 | 触发时机 | 主要属性 |
| ---------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `search_submitted` | 使用站内搜索 | keyword（搜索关键词）、resultCount（结果数量） |
| `collection_viewed` | 访问商品集合（列表）页 | id（集合 ID）、name（集合名称）、productCount（商品数量） |
| `product_viewed` | 访问商品详情页 | sku、name（商品名称）、type / spu（商品类型）、price、currencyCode、url（商品链接）、imageUrl（商品图片） |
| `product_added_to_cart` | 加入购物车 | url、name、sku、spu、quantity、price、currencyCode |
| `product_removed_from_cart` | 从购物车移除商品 | url、name、sku、spu、quantity、price、currencyCode |
| `cart_viewed` | 访问购物车页 | totalQuantity（购物车商品总数）、lines（商品列表，每项含 url、name、sku、spu、quantity、price、currencyCode） |
| `checkout_started` | 进入结账流程 | totalPrice（订单小计）、currencyCode、email、products（商品列表，字段同上） |
| `checkout_contact_info_submitted` | 提交联系方式 | email |
| `checkout_address_info_submitted` | 提交收货地址 | email |
| `checkout_shipping_info_submitted` | 提交投放方式 | email |
| `payment_info_submitted` | 提交支付信息 | totalPrice（订单小计）、currencyCode、email |
| `checkout_completed` | 支付成功（订单级，一单一条，由 Shopify 订单回调在服务端生成） | order\_id（订单号）、total\_price（订单总价） |
| `checkout_completed_order` | 支付成功的商品明细（商品级，一单内每个商品一条，与 `checkout_completed` 一起发送） | price、sku、quantity、title / name（商品名称）、product\_id（商品 ID）、orderid（订单id） |
{% hint style="info" %}
* 所有金额类属性均不带货币单位，货币由 currencyCode 指定。
* 取不到的属性不会上报，不会传空值。
{% endhint %}
## Cookie 同意管理（GDPR 合规）
为满足欧盟《通用数据保护条例》（GDPR）的要求，Ptengine for Shopify 已集成 Shopify 原生的 Cookie 同意管理框架：
* 访客拒绝非必要 Cookie 时，Ptengine 的代码会**自动停止加载**，不采集任何数据；访客同意后即时恢复采集。
* 同意状态由 Shopify 在系统层面校验，商家无需额外配置。
如果您的业务需要在访客拒绝 Cookie 后仍然采集数据，请改用[手动部署代码](/cn/start-guide/othertag/tag-shopify.md)的方式，并按自身的合规策略自行配置。请注意，这种情况下 GDPR 合规责任由商家自行承担。面向欧洲市场的客户建议优先使用应用方式；如需自定义实施，请先咨询专业的数据保护法律顾问。
## 常见问题
### 如何确认 Shopify 主账号？
在 Shopify 后台点击左下角“设置”，“通用”页面顶部的“商店详细信息”中即可看到当前商店的主账号（店主）信息。
### 如何确认 Ptengine 档案内的权限？
**第一步**：进入您的档案，点击右上角的齿轮图标，选择“成员管理”。
**第二步**：在成员列表的“权限”列查看各账号的权限。
**第三步**：点击权限处的下拉菜单可以修改已有成员的权限，点击右上角“邀请成员”可以邀请新成员并指定权限。
{% hint style="info" %}
邀请成员后，被邀请人无需到邮箱确认，会直接获得指定的权限。
{% endhint %}
各权限的详细说明见[成员邀请和权限授予](/cn/start-guide/quick/member-invitation.md)。
### 如何删除已有的基础代码和事件代码？
如果商店之前按[手动部署代码](/cn/start-guide/othertag/tag-shopify.md)的方式部署过 Ptengine，安装应用前请先删除，避免重复采集。
**删除基础代码**
**第一步**：在 Shopify 后台进入“在线商店”→“模板”，点击当前模板右侧的“···”，选择“编辑代码”。
**第二步**：打开 layout 目录下的 theme.liquid，找到 `` 到 `` 之间的代码并删除，然后点击右上角“保存”。
**删除事件代码**
**第一步**：点击 Shopify 后台左下角“设置”。
**第二步**：进入“客户事件”，找到之前添加的 Ptengine 自定义像素（例如“pt tracking on checkouts”），点击“···”→“删除”。
### 如何设置 Ptengine 账号密码？
通过 Shopify 安装后首次使用 Ptengine 时，主账号尚未设置密码。请前往[密码重置页面](https://www.ptengine.com/app/forget?email=)，或在 Ptengine 登录页选择“忘记密码”，按提示为主账号邮箱设置密码。