Ptengine for Shopify 应用安装

Ptengine for Shopify 是 Ptengine 为 Shopify 平台开发的专用应用，符合 Shopify 的平台安全规范。安装后会自动完成基础代码部署，并自动采集加购、结账、支付完成等关键行为事件（详见下方「应用自动采集的事件」）。Ptengine 基于这些数据帮您更快洞察访客在商店中的行为，并通过 A/B 测试、弹窗等个性化工具快速验证优化假设，提升页面表现。

Shopify 商店可以通过以下两种方式部署 Ptengine，本文介绍方式一：

部署方式	适合谁	说明
方式一：安装 Ptengine for Shopify 应用（推荐，本文）	使用 Shopify 在线商店主题的商店	在 Shopify 应用商店安装后自动部署基础代码，并自动采集关键行为事件，无需改动主题代码
方式二：手动部署代码	无法安装应用，或需要在访客拒绝 Cookie 后仍采集数据的商店	在 theme.liquid 中粘贴基础代码，并在「客户事件」中添加自定义像素事件代码

无头（Headless）商店，例如使用 Hydrogen 或自建前端的商店，没有 Shopify 主题，无法通过应用嵌入部署，暂不适用本文的安装方式。请联系我们获取对应的部署方案。

安装前的准备

安装后 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 的页面：

为保障数据安全，只有档案的【创建者】或【管理员】可以连接数据。情况 1 和情况 3 连接前，如果商店之前手动部署过 Ptengine 代码，请先按常见问题「如何删除已有的基础代码和事件代码」删除，避免重复采集。

第三步：复制安装代码

进入「安装代码」页面，点击「复制代码」复制基础代码。

第四步：前往 Shopify 主题编辑器粘贴代码

点击「去 Shopify 安装」，会打开 Shopify 主题编辑器的「应用嵌入」面板。确认 Ptengine 的 App Embed 开关已打开，把刚复制的代码粘贴到「Tag Installation」输入框，然后点击右上角「保存」。

第五步：验证安装是否成功

回到 Ptengine 的「安装代码」页面，在第 3 步输入商店任意页面的 URL，点击「检查」。提示「成功检测到代码」即表示安装完成，点击「进入 Ptengine」开始使用。安装了监测代码的页面被访问后，数据大约在 30 分钟后显示。

安装后的使用方法与注意事项

安装后，在 Shopify 后台左侧菜单点击「应用」，在已安装的应用中找到 Ptengine 即可进入。

Shopify 中应用的使用权限由主账号分享给其他成员，因此从 Shopify 后台进入 Ptengine 时，一律以主账号身份登录。团队成员也可以用各自的 Ptengine 账号直接访问 ptengine.com 使用。

如果主账号之前没有创建过 Ptengine 账号，安装应用后请先设置账号密码，方法见下方常见问题「如何设置 Ptengine 账号密码」。

Ptengine for Shopify 以应用嵌入（App Embed）的形式安装在当前主题中。更换主题后 Ptengine 的监测会失效，请在更换主题前联系我们，以确保数据统计不受影响。

应用自动采集的事件

安装应用后，以下事件会自动采集，无需再手动部署事件代码。

事件名	触发时机	主要属性
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）

• 所有金额类属性均不带货币单位，货币由 currencyCode 指定。

• 取不到的属性不会上报，不会传空值。

Cookie 同意管理（GDPR 合规）

为满足欧盟《通用数据保护条例》（GDPR）的要求，Ptengine for Shopify 已集成 Shopify 原生的 Cookie 同意管理框架：

• 访客拒绝非必要 Cookie 时，Ptengine 的代码会自动停止加载，不采集任何数据；访客同意后即时恢复采集。

• 同意状态由 Shopify 在系统层面校验，商家无需额外配置。

如果您的业务需要在访客拒绝 Cookie 后仍然采集数据，请改用手动部署代码的方式，并按自身的合规策略自行配置。请注意，这种情况下 GDPR 合规责任由商家自行承担。面向欧洲市场的客户建议优先使用应用方式；如需自定义实施，请先咨询专业的数据保护法律顾问。

常见问题

如何确认 Shopify 主账号？

在 Shopify 后台点击左下角「设置」，「通用」页面顶部的「商店详细信息」中即可看到当前商店的主账号（店主）信息。

如何确认 Ptengine 档案内的权限？

**第一步：**进入您的档案，点击右上角的齿轮图标，选择「成员管理」。

**第二步：**在成员列表的「权限」列查看各账号的权限。

**第三步：**点击权限处的下拉菜单可以修改已有成员的权限，点击右上角「邀请成员」可以邀请新成员并指定权限。

邀请成员后，被邀请人无需到邮箱确认，会直接获得指定的权限。

各权限的详细说明见成员邀请和权限授予。

如何删除已有的基础代码和事件代码？

如果商店之前按手动部署代码的方式部署过 Ptengine，安装应用前请先删除，避免重复采集。

删除基础代码

**第一步：**在 Shopify 后台进入「在线商店」→「模板」，点击当前模板右侧的「···」，选择「编辑代码」。

**第二步：**打开 layout 目录下的 theme.liquid，找到 <!-- Ptengine Tag --> 到 <!-- End Ptengine Tag --> 之间的代码并删除，然后点击右上角「保存」。

删除事件代码

**第一步：**点击 Shopify 后台左下角「设置」。

**第二步：**进入「客户事件」，找到之前添加的 Ptengine 自定义像素（例如「pt tracking on checkouts」），点击「···」→「删除」。

如何设置 Ptengine 账号密码？

通过 Shopify 安装后首次使用 Ptengine 时，主账号尚未设置密码。请前往密码重置页面，或在 Ptengine 登录页选择「忘记密码」，按提示为主账号邮箱设置密码。