前提条件
开始之前，请确保您具备：- 已安装 Vendo 应用 的 Shopify 商店
- OneSignal 账户和应用（Web 平台）
- 您的 OneSignal App ID（必填）
- 您的 OneSignal REST API Key（服务端事件（如订单同步和用户标签）所必需）
OneSignal 设置
创建 OneSignal 应用
登录 onesignal.com 并创建或选择一个应用。选择 Web 作为平台，并选择 Custom Code 作为集成类型。
配置 Web 推送设置
在您的 OneSignal 应用中，导航至 Settings > Push & In-App > Web Settings，或按照 Web 推送设置 指南操作。站点设置
- Site Name：您的商店名称，用作默认通知标题。
- Site URL：您 Shopify 商店的公开访问 URL（例如
https://yourstore.com）。- 必须是您网站的确切源。
- 如果客户通过自定义域名（如
https://your-site.com/）访问您的网站，请勿使用https://your-site.myshopify.com/。
- Default Icon URL：为通知提示和消息上传 256x256px 的正方形 PNG 或 JPG 图像。如果未设置，则使用铃铛图标。
配置 Service Worker 路径
Shopify 不允许从网站根目录提供文件，因此您必须告知 OneSignal Vendo 在何处提供 service worker 文件。在 OneSignal 中，前往 Settings > Push & In-App > Web Settings，向下滚动至 Advanced Push Settings，然后配置：
| 设置 | 值 |
|---|---|
| Service Worker Path | /apps/vendo/ |
| Service Worker Filename | OneSignalSDKWorker.js |
| Updater Filename | OneSignalSDKWorker.js |
| Service Worker Registration Scope | /apps/vendo/ |
https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js 提供所需的 OneSignalSDKWorker.js 文件——无需手动上传文件。Updater Filename 和 Service Worker Filename 是同一个文件。OneSignal v16+ 将单个 service worker 用于两种目的。
复制您的凭据
在 OneSignal 中，前往 Settings > Keys & IDs 并复制您的 App ID 和 REST API Key。您将在 Vendo 中输入这些内容。
Vendo 设置
添加 OneSignal 集成
在 Vendo 中，导航至 Integrations > Add Integration > OneSignal（或 Destinations > OneSignal）。
启用 Vendo 主题块
Vendo 主题块负责在您的店面加载 OneSignal SDK。没有它，推送提示将不会显示，客户端跟踪也将无法工作。
- 在您的 Shopify 后台，前往 Online Store > Themes > Customize。
- 点击 App embeds（左侧边栏中的拼图图标）。
- 开启 Vendo。
- 点击 Save。
选择要同步的事件
在 Vendo 应用的 OneSignal > Events 下，启用您要发送到 OneSignal 的客户端和服务端事件。完整事件列表请参阅下方的跟踪。
跟踪
用户识别
Vendo 采用仅限已识别用户的方式——匿名访客不会在 OneSignal 中被跟踪。用户必须通过以下四种方法之一进行识别，才能发送事件。这可以防止重复用户并确保数据干净、可操作。| 方法 | 工作原理 | 使用的标识符 |
|---|---|---|
| Web 推送订阅 | 访客在推送提示中点击”允许”。OneSignal 自动创建用户，Vendo 捕获 OneSignal ID。 | OneSignal ID |
| 邮件订阅 | 访客提交邮件订阅或电子邮件表单。Vendo 捕获邮件并调用 OneSignal.login(email)。 | |
| 客户登录 | 客户登录其 Shopify 账户。Vendo 检测到此操作并使用配置的标识符调用 OneSignal.login()。 | Shopify Customer ID 或 Email |
| 完成结账 | 客户完成购买。Vendo 存储标识符并调用 OneSignal.login()。 | Shopify Customer ID 或 Email |
身份合并
如果推送订阅者（通过 OneSignal ID 识别）后来登录或完成购买，Vendo 会使用其 Shopify Customer ID 或电子邮件调用OneSignal.login()。OneSignal 将推送订阅链接到已识别的用户——不会创建重复用户。所有过去的推送订阅都会保留，服务端事件（订单、履行）也会到达正确的用户配置文件。
客户标签
Vendo 将客户属性作为标签同步到 OneSignal 以进行细分。所有值均以字符串形式存储（OneSignal 的原生格式）。| 标签 | 描述 |
|---|---|
email | 客户电子邮件 |
first_name | 名字 |
last_name | 姓氏 |
total_spent | 终身消费金额 |
order_count | 总订单数 |
verified_email | "true" 或 "false" |
tax_exempt | "true" 或 "false" |
marketing_state | 营销同意状态 |
first_order_date | 首次订单日期（ISO 8601） |
last_order_date | 最近订单日期（ISO 8601） |
customer_created_at | 客户创建日期 |
customer_tags | 逗号分隔的 Shopify 标签 |
email_marketing_consent | 营销订阅状态 |
客户端事件
Vendo 通过 Shopify Web Pixel 跟踪店面上的客户端自定义事件，并将其发送到 OneSignal。这些事件仅在用户被识别后发送。| 事件 | 描述 |
|---|---|
page_viewed | 客户访问页面（店面、结账或订单状态） |
product_viewed | 客户查看产品详情页 |
collection_viewed | 客户查看产品系列页 |
search_submitted | 客户在店面执行搜索 |
product_added_to_cart | 产品被加入购物车 |
product_removed_from_cart | 产品从购物车中移除 |
cart_viewed | 客户查看购物车页面 |
checkout_started | 客户开始结账 |
checkout_contact_info_submitted | 提交联系信息步骤 |
checkout_address_info_submitted | 提交地址信息步骤 |
checkout_shipping_info_submitted | 已选择配送方式 |
payment_info_submitted | 已提交付款详情 |
checkout_completed | 结账成功完成 |
服务端事件
Shopify 商务事件通过 Vendo 管道导出并转发到 OneSignal。这些事件始终使用 Shopify Customer ID 作为external_id。
| 事件 | 描述 |
|---|---|
received_orders | 创建新订单 |
fulfilled_orders | 订单已履行/发货 |
delivered_orders | 订单已送达 |
refunded_orders | 订单已全额退款 |
partially_refunded_orders | 订单已部分退款 |
abandoned_checkouts | 结账被放弃 |
通用事件属性
所有事件均包含以下属性（以字符串形式）：| 属性 | 描述 |
|---|---|
order_id | 显示订单标识符 |
shopify_order_id | Shopify 内部订单 ID |
email | 客户电子邮件 |
currency | 订单货币 |
source | 事件来源 |
version | 集成版本 |
数据同步频率
| 数据类型 | 同步频率 |
|---|---|
| 客户标签 | 每 4–6 小时 |
| 订单事件 | 近实时（几分钟内） |
| 废弃购物车 | 每 1–2 小时 |
| 履行事件 | 近实时 |
平台详情
| 设置 | 值 |
|---|---|
| 同步方式 | 通过 Vendo 的客户端 + 服务端 |
| 身份标识 | Shopify Customer ID、Email 或 OneSignal ID |
| 去重 | 每个事件使用 UUID v5 哈希 |
| 批量大小 | 每次请求 1,000 个事件 |
| 数据格式 | 所有值以字符串形式存储 |
使用场景
废弃购物车找回
创建由abandoned_checkouts 事件触发的 Journey。在放弃后等待 1 小时，然后使用 checkout_url 属性发送带有找回链接的推送通知。
订单状态更新
为fulfilled_orders 和 delivered_orders 创建 Journey，在订单发货和送达时立即发送包含跟踪信息的推送通知。
VIP 客户互动
创建total_spent 大于某个阈值的细分受众，然后发送使用 first_name 标签个性化的专属优惠。
重新激活营销活动
通过创建last_order_date 超过 90 天的细分受众来定向不活跃客户，并发送赢回营销活动。
兼容来源
OneSignal 支持以下 Vendo 数据来源：| 来源 | 事件 | 用户标签 | 受众 |
|---|---|---|---|
| Shopify | 是 | 是 | 是 |
| Stripe | 是 | 是 | 是 |
| Mixpanel | — | — | 是 |
| Segment | — | — | 是 |
| Amplitude | — | — | 是 |
测试
验证 service worker
在浏览器中访问
https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js。您应该能看到 JavaScript 代码。如果收到 404，请确认 Vendo 应用已安装。您也可以打开浏览器 DevTools（F12），前往 Application > Service Workers，确认 OneSignalSDKWorker.js 已注册，作用域为 /apps/vendo/。故障排除
Service worker 返回 404
Service worker 必须位于/apps/vendo/OneSignalSDKWorker.js。如果您在根路径（/OneSignalSDKWorker.js）看到 404 错误，说明 service worker 路径未在 OneSignal 中配置——请按照 service worker 配置步骤 操作。如果 404 出现在 /apps/vendo/ 路径，请确认 Vendo 应用已安装且主题块已启用。
推送提示未显示
检查 App embeds 中 Vendo 主题块是否已启用。确认您的浏览器允许通知（点击地址栏中的锁定图标）。尝试在无痕/隐私窗口中操作，以防提示之前已被拒绝。标签未出现在 OneSignal 中
标签仅对已识别用户同步——匿名访客不会被跟踪。确保用户已通过推送订阅、登录、邮件订阅或结账进行了识别。初始标签同步可能需要几个小时。事件未触发
在 Vendo 应用的 OneSignal > Events 下确认事件已启用。客户端事件需要 Shopify Web Pixel 处于活动状态且用户已被识别。服务端事件需要配置 REST API Key。通知显示”已送达”但未出现
集成正在正常工作——问题出在您的浏览器或操作系统通知设置上。检查您的操作系统中浏览器的通知设置，确保勿扰/专注模式已关闭，并确认浏览器级别的通知权限。常见问题
设置后可以更改客户标识符吗？
可以。在 Vendo 应用的 Settings > Customer Identifier 中更新设置。如果现有用户已使用之前的方法进行了识别，更改标识符可能会创建独立的用户配置文件。Vendo 集成是否支持移动应用？
Vendo 集成专注于 Shopify 店面和 Web 推送。如果您还有移动应用，请确保您在 Vendo 中选择的标识符与移动应用中使用的标识符匹配，以使用户配置文件保持一致。如果访客始终未被识别会怎样？
未识别访客的事件不会发送到 OneSignal。一旦访客识别自己（通过订阅推送、登录、注册邮件或完成结账），Vendo 就开始发送事件。这种仅识别用户的方式可以防止重复用户并确保数据干净。Vendo 为什么采用仅识别用户的方式？
以前的版本使用 Shopify 的 session cookie 作为标识符来跟踪匿名访客。这会创建无法正确合并的重复 OneSignal 用户，导致用户数虚高和数据碎片化。仅识别用户的方式确保每个 OneSignal 用户都是真实的且可操作的。相关页面
Keys & IDs
查找您的 OneSignal App ID 和 REST API 密钥。
自定义事件
跟踪用户行为并根据 Shopify 事件触发自动化。
Web 推送设置
为您的 Shopify 商店设置 Web 推送通知。
Web 权限提示
配置向访客请求 Web 推送权限的方式和时间。