跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

OneSignal 已与 Vendo 合作，打造无缝的 Shopify 集成方案。Vendo 只需一键即可在您的 Shopify 店面部署 OneSignal SDK，无需手动编辑主题代码。它将客户标签、客户端浏览事件和服务端商务事件同步到 OneSignal，让您能够基于真实行为和购买历史构建细分受众并触发推送营销活动。 有关 Vendo 的文档，请参阅 Vendo OneSignal Destination。

​
前提条件

开始之前，请确保您具备：
  • 已安装 Vendo 应用 的 Shopify 商店
  • OneSignal 账户和应用（Web 平台）
  • 您的 OneSignal App ID（必填）
  • 您的 OneSignal REST API Key（服务端事件（如订单同步和用户标签）所必需）

​
OneSignal 设置

1

创建 OneSignal 应用

登录 onesignal.com 并创建或选择一个应用。选择 Web 作为平台，并选择 Custom Code 作为集成类型。
2

配置 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 图像。如果未设置，则使用铃铛图标。
3

配置 Service Worker 路径

Shopify 不允许从网站根目录提供文件，因此您必须告知 OneSignal Vendo 在何处提供 service worker 文件。在 OneSignal 中，前往 Settings > Push & In-App > Web Settings，向下滚动至 Advanced Push Settings，然后配置：
设置值
Service Worker Path/apps/vendo/
Service Worker FilenameOneSignalSDKWorker.js
Updater FilenameOneSignalSDKWorker.js
Service Worker Registration Scope/apps/vendo/
OneSignal Advanced Push Settings showing service worker paths configured for Vendo
Vendo 会自动在 https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js 提供所需的 OneSignalSDKWorker.js 文件——无需手动上传文件。
Updater Filename 和 Service Worker Filename 是同一个文件。OneSignal v16+ 将单个 service worker 用于两种目的。
4

复制您的凭据

在 OneSignal 中，前往 Settings > Keys & IDs 并复制您的 App ID 和 REST API Key。您将在 Vendo 中输入这些内容。

​
Vendo 设置

1

安装 Vendo 应用

从 Shopify 应用商店安装 Vendo 应用。
2

添加 OneSignal 集成

在 Vendo 中，导航至 Integrations > Add Integration > OneSignal（或 Destinations > OneSignal）。
Vendo Integrations page showing the OneSignal integration option
3

输入您的 OneSignal 凭据

输入上一节中的 OneSignal App ID 和 REST API Key，然后点击 Save。
4

启用 Vendo 主题块

Vendo 主题块负责在您的店面加载 OneSignal SDK。没有它，推送提示将不会显示，客户端跟踪也将无法工作。
  1. 在您的 Shopify 后台，前往 Online Store > Themes > Customize。
  2. 点击 App embeds（左侧边栏中的拼图图标）。
  3. 开启 Vendo。
  4. 点击 Save。
主题块负责处理 SDK 初始化、service worker 注册、推送提示显示、用户识别（推送订阅、登录、邮件订阅）和标签同步。
5

选择要同步的事件

在 Vendo 应用的 OneSignal > Events 下，启用您要发送到 OneSignal 的客户端和服务端事件。完整事件列表请参阅下方的跟踪。
6

历史数据同步（可选）

Vendo 可以将现有客户和近期订单历史记录回填到 OneSignal。保存凭据后，此过程会在后台自动进行。
Vendo historical data settings showing sync options for Shopify data

​
跟踪

​
用户识别

Vendo 采用仅限已识别用户的方式——匿名访客不会在 OneSignal 中被跟踪。用户必须通过以下四种方法之一进行识别，才能发送事件。这可以防止重复用户并确保数据干净、可操作。
方法工作原理使用的标识符
Web 推送订阅访客在推送提示中点击”允许”。OneSignal 自动创建用户，Vendo 捕获 OneSignal ID。OneSignal ID
邮件订阅访客提交邮件订阅或电子邮件表单。Vendo 捕获邮件并调用 OneSignal.login(email)。Email
客户登录客户登录其 Shopify 账户。Vendo 检测到此操作并使用配置的标识符调用 OneSignal.login()。Shopify Customer ID 或 Email
完成结账客户完成购买。Vendo 存储标识符并调用 OneSignal.login()。Shopify Customer ID 或 Email
如果您有移动应用或第三方连接，请选择与其他工具相匹配的标识符（Shopify Customer ID 与 Email），以使用户配置文件在各平台保持一致。在 Vendo 应用的 Settings > Customer Identifier 中进行配置。

​
身份合并

如果推送订阅者（通过 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结账成功完成
Vendo client-side events settings showing available custom events

​
服务端事件

Shopify 商务事件通过 Vendo 管道导出并转发到 OneSignal。这些事件始终使用 Shopify Customer ID 作为 external_id。
事件描述
received_orders创建新订单
fulfilled_orders订单已履行/发货
delivered_orders订单已送达
refunded_orders订单已全额退款
partially_refunded_orders订单已部分退款
abandoned_checkouts结账被放弃
Vendo server-side events settings showing available Shopify webhook events

​
通用事件属性

所有事件均包含以下属性（以字符串形式）：
属性描述
order_id显示订单标识符
shopify_order_idShopify 内部订单 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——是
事件和用户标签需要 Shopify 或 Stripe 作为数据来源。受众细分可以从 BigQuery 数据集中的任何来源数据构建。

​
测试

1

验证 service worker

在浏览器中访问 https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js。您应该能看到 JavaScript 代码。如果收到 404，请确认 Vendo 应用已安装。您也可以打开浏览器 DevTools（F12），前往 Application > Service Workers，确认 OneSignalSDKWorker.js 已注册，作用域为 /apps/vendo/。
2

测试推送提示

在无痕/隐私窗口中打开您的店面。您应该能看到 OneSignal 通知权限提示。点击 Allow 以订阅。
3

发送测试通知

在 OneSignal 仪表板中，前往 Messages > Push > New Message。向您的订阅者发送测试通知并确认其显示。
4

在 OneSignal 中验证用户数据

前往 Audience > Subscriptions，确认您的测试订阅显示。检查已识别用户的用户标签（电子邮件、姓名等）是否正在同步。
5

触发测试事件

在您的商店中浏览产品或完成测试结账。确认事件出现在 OneSignal 仪表板中用户的活动中。

​
故障排除

​
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 推送权限的方式和时间。