数据源

• 用户当前的奖励余额
• 最新订单状态
• 个性化产品推荐

​

数据源的工作原理

1. 创建数据源 – 配置 OneSignal 如何连接到您的 API。
2. 将数据源附加到消息模板。
3. 使用 Liquid 语法在消息中插入响应字段。
4. 在发送时，OneSignal 为每个收件人进行 API 调用，解析响应，并将数据注入到您的消息中。

​

示例：显示奖励积分

Hi {{ first_name }},

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

Keep shopping to earn more points!

​

创建和使用数据源

​

1. 设置您的数据源配置

• 名称：描述性名称，如”客户奖励 API”，帮助您区分数据源。建议使用唯一名称，但不是必需的。
• 别名：像 rewards 这样的简短标识符，用于 Liquid 语法（例如 {{ data_feed.rewards.points }}）。必须唯一，小写字母数字字符，不含空格或特殊字符。
• 方法：OneSignal 联系您的 API 所使用的 HTTP 方法。通常为 GET，但也支持 POST。
• URL：您的 API 端点。支持 Liquid 语法，使 OneSignal 能够获取特定用户的数据。

https://acme.com/customers/user_id={{ external_id }}/rewards

• 标头：您的 API 所需的键值对（例如身份验证令牌）。支持 Liquid 语法。
• 请求体：可选的 JSON 请求体。支持 Liquid 语法，与 Journey Webhooks 相同。

{
	"customer_id": "{{ subscription.external_id }}"
}

​

2. 将数据源附加到您的消息模板

1. 导航至消息 > 模板
2. 在消息部分，选择个性化按钮

3. 打开数据源并选择您的数据源

4. 保存您的模板

​

3. 在消息中使用数据

{
	"external_id": "a1-b2c3",
	"points": 193,
	"status_level": "Gold"
}

You have {{ data_feed.rewards.points }} points!
Your membership status is {{ data_feed.rewards.status_level }}.

• 使用数据源
• 使用 rewards 数据源
  • 请记住：rewards 数据源知道用收件人的 external_id 调用 API
• 从响应中，插入 points 项的值（193）和 status_level 项的值（Gold）

​

要求和限制

• 接受单步身份验证，在标头中使用身份验证令牌
• 快速响应。 推荐在 250 毫秒以内（这直接影响发送速度）
• 返回 JSON。 目前不支持其他格式。
  • 如果您需要其他格式，请分享您的用例。
• 处理您的发送量。 如果您的 API 速率限制较低，会减慢消息投递速度。
• 返回合理大小的负载。 建议保持响应在 50 KB 以下以获得最佳性能。

• 每个模板一个数据源。 在单次 API 响应中获取您需要的所有数据。
• 每个数据源每条消息一次 API 调用。
• 仅限 Journeys。 尚未适用于其他发送方法。
• 没有链式调用。 一个数据源的负载不能用于调用另一个数据源。

​

设置您的 API

​

身份验证

Authorization: Bearer YOUR_TOKEN

X-API-Key: YOUR_KEY

​

JSON 请求体

​

JSON 响应

​

个性化参数

https://api.example.com/users/{{external_id}}/data
https://api.example.com/rewards?email={{email | url_encode}}

{
	"customer_id": "{{ external_id }}",
	"email": "{{ subscription.email }}"
}

​

速率限制

​

错误处理

​

入门清单

• 我想在消息中显示什么数据？从包含要从 API 填充的项目的简单大纲开始，有助于整理思路。
• 这些数据是否可以通过单个 API 端点获得？
• 我将如何验证 API 请求？
• 我将使用什么标识符或其他数据项来获取个性化数据？
• 该标识符是否已经存储在 OneSignal 中？如果没有，将如何填充？
• 我的 API 能否处理我将产生的请求量？
• 如果我的 API 没有用户数据会怎样？

​

示例和高级用例

• 循环迭代：废弃购物车
• 自定义事件属性
• 条件显示：订单状态
• 无个性化的自动化
• 个性化优惠券码

假设您有一个数据源 cart，它返回用户购物车中的商品数组，以及购物车的总金额：

{
  "items": [
    {
      "name": "Blue Running Shoes",
      "price": 84.00,
      "image_url": "https://acme.com/blue-running-shoes.png"
    },
    {
      "name": "Protein Bar",
      "price": 5.99,
      "image_url": "https://acme.com/protein-bar.png"
    }
  ],
  "total": 89.99
}

如果您想显示购物车中的每个商品以及购物车总额，您可以在 Liquid 中使用 for 循环：

<ul>
  {% for item in data_feed.cart.items %}
    <li>
      <strong>{{ item.name }}</strong><br>
      ${{ item.price }}<br>
      <img src="{{ item.image_url }}" alt="{{ item.name }}">
    </li>
  {% endfor %}
</ul>

<p>Cart total: ${{ data_feed.cart.total }}</p>

这将产生：

- Blue Running Shoes
- $84.00
- <running shoes image>
- Protein Bar
- $5.99
- <protein bar image>
Cart total: $89.99

如果您使用电子邮件块编辑器，当插入这种复杂的 Liquid 语法时，特别是如果您需要包含图像或链接，最好使用自定义 HTML 块元素以获得最佳结果。

想了解如何使用自定义事件触发此废弃购物车邮件？请查看自定义事件属性标签页了解完整工作流程。

继续上一个废弃购物车示例，我们首先如何知道要获取那个特定的购物车呢？一种方法可能是创建一个由 cart_abandoned 自定义事件触发的 Journey，其中属性包含 cart_id。在此示例中，该事件通过 API 发送到 OneSignal：

curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/custom_events \
  --header 'Accept: application/json' \
  --data '{
  "events": [
    {
      "name": "cart_abandoned",
      "external_id": "user_12345",
      "properties": {
        "cart_id": 98765
      }
    }
  ]
}'

当此事件触发时，用户 user_12345 进入旅程，然后到达发送电子邮件的节点。该电子邮件模板使用 cart 数据源设置，其中 URL 设置为检索特定购物车的内容，如下所示：

https://acme.com/carts/{{ journey.event.cart_abandoned.data.cart_id }}

因此，当摄取此特定事件并触发 Journey 时：

1. cart_id 值 98765 将存储到 Journey 中
2. 当到达电子邮件步骤时，cart 数据源将引用该 cart_id 值并使用它来调用购物车 API
3. 返回的 JSON 属性将被解析并插入到电子邮件中，如上面的示例所示

想了解如何根据订单状态有条件地显示数据源内容？请查看条件显示：订单状态标签页了解更多。

假设您想包含客户订单的状态，但仅在订单已发货时才包含跟踪号链接。您可以使用 if 语句来实现：

Your order is {{data_feed.order.status}}!

{% if data_feed.order.tracking_number != empty %}
Track it here: {{data_feed.order.tracking_url}}
{% endif %}

在这里，只有在 tracking_number 存在时才会显示跟踪链接。

数据源可以用于自动向您的消息中插入最新信息，而不一定需要针对每个收件人进行个性化。例如，您可能在电子邮件顶部插入横幅图像，并每月更改以跟上节假日和其他月度活动。与其每月记得向 OneSignal 上传新图像并更改所有模板，您可以设置一个数据源，从您的 CMS 或其他资产管理位置获取当前横幅图像 URL。您将设置一个 banner 数据源，指向 URL 中不含任何变量的端点，如下所示：

https://acme.com/assets/email-banner

它返回包含当前横幅 URL 的响应：

{
	"banner_url": "https://acme.com/assets/email-banner/2025july.png"
}

您将设置您的电子邮件模板使用 {{ data_feed.banner.banner_url }} 作为图像源 URL，从而自动化此流程。

本示例介绍如何使用数据源在电子邮件中发送个性化的一次性优惠券码，该数据源会在发送时通过 API 为每个收件人获取唯一值。

​

目标

发送如下电子邮件：

您好 George， 在接下来的 2 小时内完成预订，使用您的专属码 XYZ123ABC 立享 10% 折扣

每个用户收到唯一的优惠券码，在发送电子邮件时通过外部 API 实时生成，在给定时间窗口内有效，且与该用户绑定。

​

前提条件

• 在 OneSignal 中已配置电子邮件渠道（您的应用已启用电子邮件功能）
• 一个外部 API，接受用户标识符（例如 external_id）和活动标识符，并返回包含优惠券码、折扣和到期时间的 JSON
• 每个用户的唯一标识符（如 external_id），您的 API 可用其生成优惠券
• 用于通过 OneSignal Journey 发送电子邮件的细分或触发条件（例如”过去 24 小时内的废弃搜索”）

​

第 1 步：创建数据源

1

导航至数据源

在您的 OneSignal 应用中，从导航栏选择数据源，然后点击新建数据源。

2

配置数据源

配置以下字段：

• 数据源名称：coupon_code_generator
• 别名：coupon
• 方法：GET
• URL：https://api.example.com/generate-coupon?userId={{ external_id }}&campaign=AbandonedBooking10
• 标头：
  {
    "Authorization": "Bearer YOUR_API_TOKEN"
  }
  

3

引用 API 响应

当 API 返回如下 JSON 时：

{
  "code": "AB10-5F3K-HT9L",
  "discount_percent": "10%",
  "expires_in_hours": 2
}

您可以在电子邮件模板中引用其值：

• {{ data_feed.coupon.code }}
• {{ data_feed.coupon.discount_percent }}
• {{ data_feed.coupon.expires_in_hours }}

4

测试并激活数据源

点击发送测试以验证您的配置，然后点击激活使数据源可在模板中使用。

​

第 2 步：创建电子邮件模板

1. 在 OneSignal 中，转到消息 → 电子邮件 → 新建模板
2. 在消息正文中使用数据源别名和字段。例如：

<h2>Hi {{ first_name }},</h2>
<p>
Complete your booking in the next {{ data_feed.coupon.expires_in_hours }} hours and save
{{ data_feed.coupon.discount_percent }} with your personal code:
<strong>{{ data_feed.coupon.code }}</strong>
</p>

<p><a href="https://example.com/checkout?coupon={{ data_feed.coupon.code }}">Use Code Now →</a></p>

• 使用 {{ data_feed.<alias>.<field> }} 格式的 Liquid 语法
• 确保数据源已附加到模板
• 如果使用拖放编辑器并包含自定义 Liquid 逻辑，请使用 HTML 块

​

第 3 步：附加数据源并触发电子邮件

1. 在模板编辑器中，在个性化下，打开数据源并选择您的数据源（coupon_code_generator）
2. 这确保 OneSignal 在发送时为每个收件人进行 API 调用，填充数据并注入到电子邮件中
3. 设置 Journey 以自动发送消息：
   • 入口条件：细分，如”过去 24 小时内的废弃搜索”
   • 等待直到：创建 booking_completed 自定义事件。配置等待条件，如果此事件触发则退出 Journey，否则在 1 小时后继续。如果用户完成预订，则退出而不接收电子邮件；否则继续接收优惠券。
   • 发送电子邮件：使用个性化优惠券电子邮件模板
   • 确保 Journey 使用电子邮件渠道，且收件人已订阅电子邮件

​

第 4 步：管理优惠券兑换和追踪

您的后端应：

1. 记录每个生成的码，包含 userId、code、campaign、expiration_time 和 redeemed 标志
2. 在结账时验证并将码标记为已兑换
3. 记录兑换数据（用户、活动和时间）以进行 ROI 分析

​

完整工作流程示例

步骤	事件	操作
1	用户触发”废弃搜索”细分	用户通过细分进入 Journey
2	Journey 触发电子邮件发送	OneSignal 附加数据源，使用用户的 external_id 和活动名称调用您的 API
3	API 返回 JSON	OneSignal 填充数据源优惠券字段并发送电子邮件
4	用户收到电子邮件	示例：“Hi George! Save 10% with your personal code: AB10-5F3K-HT9L”
5	用户兑换码	后端验证并记录兑换

​

测试

• 使用已知 external_id 的用户进行测试
• 手动调用您的 API 以确认正确的 JSON 响应
• 在 OneSignal 模板编辑器中使用预览验证数据源优惠券字段是否正确填充
• 检查 API 日志中的延迟和错误
• 如果数据源调用失败，OneSignal 将跳过向该收件人发送消息

​

常见问题

​

我的数据源值未出现在消息中，应检查什么？

1. 数据源已附加到模板（在个性化 > 数据源下）。
2. 您的 Liquid 语法与 JSON 响应结构完全匹配——{{ data_feed.<alias>.<field> }}。
3. 使用相同标识符手动调用 API 端点时返回有效 JSON。
4. 收件人在 OneSignal 中存储了所需的标识符（例如 external_id）。

​

为什么消息发送缓慢？

​

为什么某些收件人没有收到消息？

​

我能在一个模板中使用多个数据源吗？

​

数据源是否适用于推送通知或短信？

​

如果我的 API 在消息发送时宕机会怎样？

​

相关页面