> ## 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.

# Shopify

> 通过 Vendo 集成将 Shopify 连接到 OneSignal，实现 Web 推送通知、客户标签、商务事件和行为定向。

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

有关 Vendo 的文档，请参阅 [Vendo OneSignal Destination](https://docs.vendodata.com/destinations/onesignal/overview)。

## 前提条件

开始之前，请确保您具备：

* 已安装 [Vendo 应用](https://apps.shopify.com/) 的 Shopify 商店
* OneSignal 账户和应用（Web 平台）
* 您的 OneSignal **App ID**（必填）
* 您的 OneSignal **REST API Key**（服务端事件（如订单同步和用户标签）所必需）

## OneSignal 设置

<Steps>
  <Step title="创建 OneSignal 应用">
    登录 [onesignal.com](https://onesignal.com) 并创建或选择一个应用。选择 **Web** 作为平台，并选择 **Custom Code** 作为集成类型。
  </Step>

  <Step title="配置 Web 推送设置">
    在您的 OneSignal 应用中，导航至 **Settings > Push & In-App > Web Settings**，或按照 [Web 推送设置](./web-push-setup) 指南操作。

    **站点设置**

    * **Site Name**：您的商店名称，用作默认通知标题。
    * **Site URL**：您 Shopify 商店的公开访问 URL（例如 `https://yourstore.com`）。
      * 必须是您网站的确切[源](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy)。
      * 如果客户通过自定义域名（如 `https://your-site.com/`）访问您的网站，请勿使用 `https://your-site.myshopify.com/`。
    * **Default Icon URL**：为通知提示和消息上传 256x256px 的正方形 PNG 或 JPG 图像。如果未设置，则使用铃铛图标。
  </Step>

  <Step title="配置 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/`          |

    <Frame caption="Shopify 商店使用 Vendo 的 service worker 配置。">
      <img src="https://mintcdn.com/onesignal/N_-d1DtCTRgGPN4l/images/integrations/shopify/vendo-service-worker-configuration.png?fit=max&auto=format&n=N_-d1DtCTRgGPN4l&q=85&s=b7bc1794445e002bd3427c94a6ec6ccf" alt="OneSignal Advanced Push Settings showing service worker paths configured for Vendo" width="3038" height="1108" data-path="images/integrations/shopify/vendo-service-worker-configuration.png" />
    </Frame>

    Vendo 会自动在 `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js` 提供所需的 `OneSignalSDKWorker.js` 文件——无需手动上传文件。

    <Note>
      Updater Filename 和 Service Worker Filename 是同一个文件。OneSignal v16+ 将单个 service worker 用于两种目的。
    </Note>
  </Step>

  <Step title="复制您的凭据">
    在 OneSignal 中，前往 [**Settings > Keys & IDs**](./keys-and-ids) 并复制您的 **App ID** 和 **REST API Key**。您将在 Vendo 中输入这些内容。
  </Step>
</Steps>

## Vendo 设置

<Steps>
  <Step title="安装 Vendo 应用">
    从 Shopify 应用商店安装 Vendo 应用。
  </Step>

  <Step title="添加 OneSignal 集成">
    在 Vendo 中，导航至 **Integrations > Add Integration > OneSignal**（或 **Destinations > OneSignal**）。

    <Frame caption="在 Vendo 中添加 OneSignal 集成。">
      <img src="https://mintcdn.com/onesignal/PoskQI_qr0DD8jDV/images/integrations/shopify/vendo-onesignal-integrations.png?fit=max&auto=format&n=PoskQI_qr0DD8jDV&q=85&s=13acfaf4e6b01f77535f1a1386c4212d" alt="Vendo Integrations page showing the OneSignal integration option" width="2520" height="1756" data-path="images/integrations/shopify/vendo-onesignal-integrations.png" />
    </Frame>
  </Step>

  <Step title="输入您的 OneSignal 凭据">
    输入上一节中的 OneSignal **App ID** 和 **REST API Key**，然后点击 **Save**。
  </Step>

  <Step title="启用 Vendo 主题块">
    Vendo 主题块负责在您的店面加载 OneSignal SDK。没有它，推送提示将不会显示，客户端跟踪也将无法工作。

    1. 在您的 Shopify 后台，前往 **Online Store > Themes > Customize**。
    2. 点击 **App embeds**（左侧边栏中的拼图图标）。
    3. 开启 **Vendo**。
    4. 点击 **Save**。

    主题块负责处理 SDK 初始化、service worker 注册、推送提示显示、用户识别（推送订阅、登录、邮件订阅）和标签同步。
  </Step>

  <Step title="选择要同步的事件">
    在 Vendo 应用的 **OneSignal > Events** 下，启用您要发送到 OneSignal 的客户端和服务端事件。完整事件列表请参阅下方的[跟踪](#tracking)。
  </Step>

  <Step title="历史数据同步（可选）">
    Vendo 可以将现有客户和近期订单历史记录回填到 OneSignal。保存凭据后，此过程会在后台自动进行。

    <Frame caption="Vendo 中的历史数据同步选项。">
      <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-historical-data.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=4eb61a384a7ac3f4596661348f98ac48" alt="Vendo historical data settings showing sync options for Shopify data" width="1724" height="762" data-path="images/integrations/shopify/vendo-historical-data.png" />
    </Frame>
  </Step>
</Steps>

## 跟踪

### 用户识别

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 |

<Warning>
  如果您有移动应用或第三方连接，请选择与其他工具相匹配的标识符（Shopify Customer ID 与 Email），以使用户配置文件在各平台保持一致。在 Vendo 应用的 **Settings > Customer Identifier** 中进行配置。
</Warning>

#### 身份合并

如果推送订阅者（通过 OneSignal ID 识别）后来登录或完成购买，Vendo 会使用其 Shopify Customer ID 或电子邮件调用 `OneSignal.login()`。OneSignal 将推送订阅链接到已识别的用户——不会创建重复用户。所有过去的推送订阅都会保留，服务端事件（订单、履行）也会到达正确的用户配置文件。

### 客户标签

Vendo 将客户属性作为[标签](./add-user-data-tags)同步到 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 跟踪店面上的客户端[自定义事件](./custom-events)，并将其发送到 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`               | 结账成功完成             |

<Frame caption="Vendo 中的客户端事件配置。">
  <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-client-side-events.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=c94b99465b8c200ebb1bb475e492f8a1" alt="Vendo client-side events settings showing available custom events" width="865" height="726" data-path="images/integrations/shopify/vendo-client-side-events.png" />
</Frame>

### 服务端事件

Shopify 商务事件通过 Vendo 管道导出并转发到 OneSignal。这些事件始终使用 Shopify Customer ID 作为 `external_id`。

| 事件                          | 描述       |
| --------------------------- | -------- |
| `received_orders`           | 创建新订单    |
| `fulfilled_orders`          | 订单已履行/发货 |
| `delivered_orders`          | 订单已送达    |
| `refunded_orders`           | 订单已全额退款  |
| `partially_refunded_orders` | 订单已部分退款  |
| `abandoned_checkouts`       | 结账被放弃    |

<Frame caption="Vendo 中的服务端事件配置。">
  <img src="https://mintcdn.com/onesignal/dknFSNQuQfw5IM0j/images/integrations/shopify/vendo-server-side-events.png?fit=max&auto=format&n=dknFSNQuQfw5IM0j&q=85&s=c9bed30c26b0bec3b8a53eb8cde8098d" alt="Vendo server-side events settings showing available Shopify webhook events" width="865" height="394" data-path="images/integrations/shopify/vendo-server-side-events.png" />
</Frame>

### 通用事件属性

所有事件均包含以下属性（以字符串形式）：

| 属性                 | 描述              |
| ------------------ | --------------- |
| `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](./journeys-overview)。在放弃后等待 1 小时，然后使用 `checkout_url` 属性发送带有找回链接的推送通知。

### 订单状态更新

为 `fulfilled_orders` 和 `delivered_orders` 创建 Journey，在订单发货和送达时立即发送包含跟踪信息的推送通知。

### VIP 客户互动

创建 `total_spent` 大于某个阈值的[细分受众](./segmentation)，然后发送使用 `first_name` 标签个性化的专属优惠。

### 重新激活营销活动

通过创建 `last_order_date` 超过 90 天的细分受众来定向不活跃客户，并发送赢回营销活动。

## 兼容来源

OneSignal 支持以下 Vendo 数据来源：

| 来源        | 事件 | 用户标签 | 受众 |
| --------- | -- | ---- | -- |
| Shopify   | 是  | 是    | 是  |
| Stripe    | 是  | 是    | 是  |
| Mixpanel  | —  | —    | 是  |
| Segment   | —  | —    | 是  |
| Amplitude | —  | —    | 是  |

事件和用户标签需要 Shopify 或 Stripe 作为数据来源。受众细分可以从 BigQuery 数据集中的任何来源数据构建。

***

## 测试

<Steps>
  <Step title="验证 service worker">
    在浏览器中访问 `https://yourstore.myshopify.com/apps/vendo/OneSignalSDKWorker.js`。您应该能看到 JavaScript 代码。如果收到 404，请确认 Vendo 应用已安装。

    您也可以打开浏览器 DevTools（**F12**），前往 **Application > Service Workers**，确认 `OneSignalSDKWorker.js` 已注册，作用域为 `/apps/vendo/`。
  </Step>

  <Step title="测试推送提示">
    在无痕/隐私窗口中打开您的店面。您应该能看到 OneSignal 通知权限提示。点击 **Allow** 以订阅。
  </Step>

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

  <Step title="在 OneSignal 中验证用户数据">
    前往 **Audience > Subscriptions**，确认您的测试订阅显示。检查已识别用户的用户标签（电子邮件、姓名等）是否正在同步。
  </Step>

  <Step title="触发测试事件">
    在您的商店中浏览产品或完成测试结账。确认事件出现在 OneSignal 仪表板中用户的活动中。
  </Step>
</Steps>

***

## 故障排除

### Service worker 返回 404

Service worker 必须位于 `/apps/vendo/OneSignalSDKWorker.js`。如果您在根路径（`/OneSignalSDKWorker.js`）看到 404 错误，说明 service worker 路径未在 OneSignal 中配置——请按照 [service worker 配置步骤](#configure-the-service-worker-path) 操作。如果 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 用户都是真实的且可操作的。

***

## 相关页面

<Columns cols={2}>
  <Card title="Keys & IDs" icon="key" href="./keys-and-ids">
    查找您的 OneSignal App ID 和 REST API 密钥。
  </Card>

  <Card title="自定义事件" icon="bolt" href="./custom-events">
    跟踪用户行为并根据 Shopify 事件触发自动化。
  </Card>

  <Card title="Web 推送设置" icon="globe" href="./web-push-setup">
    为您的 Shopify 商店设置 Web 推送通知。
  </Card>

  <Card title="Web 权限提示" icon="bell" href="./permission-requests">
    配置向访客请求 Web 推送权限的方式和时间。
  </Card>
</Columns>