跳转到主要内容
数据源让您在发送时直接从您的 API 拉取实时数据到消息中。这让您可以提供高度个性化的内容，而无需预先将数据加载到 OneSignal 中。 当您的数据经常变化时，请使用数据源，例如：
  • 用户当前的奖励余额
  • 最新订单状态
  • 个性化产品推荐
其他个性化方法（如标签或动态内容）适用于静态数据，但数据源最适合实时、快速变化的值。
数据源目前仅适用于通过 Journeys 发送的邮件消息。 需要其他渠道？填写这份简短调查。

​
数据源的工作原理

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

​
示例：显示奖励积分

假设您想向每个客户显示他们的奖励余额： 
您好 {{ first_name }}，

您有 {{ data_feed.rewards.points }} 积分！
您的会员状态是 {{ data_feed.rewards.status_level }}。

继续购物赚取更多积分！
当 Sarah 收到这封电子邮件时，她将看到实际的积分余额和会员状态，而不是 {{ data_feed.rewards.points }} 和 {{ data_feed.rewards.status_level }}。 我们将使用这个示例在下面逐步向您展示如何设置数据源。

​
创建和使用数据源

​
1. 设置您的数据源配置

在侧边栏中导航至数据 > 数据源，查看现有数据源列表并创建新的数据源。 每个数据源必须具有：
  • 名称：描述性名称，如”客户奖励 API”，帮助您在数据源列表中区分它。我们建议这些名称是唯一的，但不是必需的。
  • 别名：像 rewards 这样的简短名称，您将在 Liquid 语法中使用。这些必须是唯一的，不能包含空格，只能包含小写字母数字字符，没有特殊符号。
  • 方法：我们应该如何联系您的 API。通常这是 GET，但也支持 POST。
  • URL：API 的地址。您可以包含 Liquid 语法，使我们能够调用 API 来获取特定用户的数据。
例如，也许您的奖励端点可能以这种方式格式化，您可以使用数据标签插入外部 ID（存储在 OneSignal 中）来获取该用户的奖励数据： 
https://acme.com/customers/user_id={{ external_id }}/rewards
  • 标头：根据您的 API 规范需要输入标头键值对。一个典型的重要用途是包含身份验证信息。如果需要，这些字段也支持 Liquid 语法。
  • 请求体：如果您的 API 需要，您可以在请求中包含 JSON 格式的请求体。此编辑器支持 Liquid 语法，就像 Journey Webhooks 一样。
例如，您的 API 可能需要您在请求体中指定用户的 ID，而不是在上面的 URL 字符串中： 
{
	"customer_id": "{{ external_id }}"
}
完整的数据源配置可能如下所示：

数据源配置示例

我们建议在使用之前测试您的数据源。 您使用测试订阅来测试它，因此请确保您的测试订阅属性将从您的 API 返回真实结果。 最后，激活您的新数据源，使其准备好使用。

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

将您的数据源附加到消息模板，让 OneSignal 知道要使用它。
  1. 导航至消息 > 模板
  2. 在消息部分，选择个性化按钮

个性化按钮选项

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

消息编辑器中的数据源部分

  1. 保存您的模板

​
3. 在消息中使用数据

使用 Liquid 语法在消息中的任何地方插入响应数据。在我们的示例中，假设对于 Sarah（其 external_id 是 1a1-b2c3）的响应是这样一个简单的 JSON 数据： 
{
	"external_id": a1-b2c3,
	"points": 193,
	"status_level": "Gold"
}
我们想要在消息中插入积分数量和状态级别，这通过典型的点表示法实现： 
您有 {{ data_feed.rewards.points }} 积分！
您的会员状态是 {{ data_feed.rewards.status_level }}。
这告诉 OneSignal：
  • 使用数据源
  • 使用 rewards 数据源
    • 回忆：rewards 数据源知道用收件人的 external_id 调用 API
  • 从响应中，插入 points 项的值（193）和 status_level 项的值（Gold）

​
要求和限制

您的 API 需要：
  • 接受单步身份验证，在标头中使用身份验证令牌
  • 快速响应。 推荐在250毫秒以内（这直接影响发送速度）
  • 返回JSON。 目前不支持其他格式。
  • 处理您的消息发送量和频率。 如果您的 API 有较低的速率限制，这将阻止我们快速投递您的消息。
  • 返回合理大小的负载。 我们建议保持响应在50kb以下以获得最佳性能。
当前限制：
  • 每个模板一个数据源。 我们预计在未来增加此限制。在此填写简短调查，让我们知道您需要这个功能。
  • 每个数据源每条消息一次 API 调用。 在一次调用中获取您需要的所有内容。
  • 仅限 Journeys。 尚未适用于其他发送方法。在此填写简短调查，让我们知道您需要这个功能。
  • 没有链式调用。 一个数据源的负载不能用于调用另一个数据源。

​
设置您的 API

在创建数据源之前，确保您的 API 能够处理这些要求：

​
身份验证

您的 API 应通过标头接受身份验证： 
Authorization: Bearer YOUR_TOKEN
或 
X-API-Key: YOUR_KEY

​
JSON 请求体

如果您需要在请求中包含请求体，您的 API 应接受 JSON。这可能意味着您的标头需要包含 Content: application/json。

​
JSON 响应

您的 API 应返回 JSON 对象。通常这意味着您的标头将包含 Accept: application/json。

​
个性化参数

您通常会在URL中传递用户标识符，如下所示： 
https://api.example.com/users/{{external_id}}/data
https://api.example.com/rewards?email={{email | url_encode}}
和/或在请求体中：
JSON
{
	"customer_id": "{{ external_id }}",
	"email": "{{ subscription.email }}"
}
确保这些数据在 OneSignal 中存在（通常作为数据标签，但也有其他选项可用，如自定义事件负载）。

​
速率限制

考虑您的 API 速率限制。如果您快速连续向10,000个用户发送，我们将进行10,000次 API 调用。确保您的 API 能够处理这个数量。

​
错误处理

如果您的 API 返回错误或没有用户数据，消息不会发送给该收件人。确保您的 API 为所有预期用户返回数据。

​
入门清单

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

​
示例和高级用例

数据源可以与 Liquid 语法结合使用，或与其他功能创造性地结合使用，以产生更复杂的个性化。

​
循环迭代：废弃购物车

假设您有一个数据源 cart，它返回用户购物车中的商品数组，以及购物车的总金额：
JSON
{
  "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 循环：
HTML
<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
curl --request POST \
  --url https://api.onesignal.com/apps/{app_id}/integrations/custom_events \
  --header 'Accept: application/json' \
  --data '{
  "events": [
    {
      "name": "cart_abandoned",
      "external_id": "user_12345",
      "payload": {
        "cart_id": 98765
      }
    }
  ]
}'

Journey 入口的自定义事件

当此事件触发时，用户 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 语句来做到这一点： 
您的订单状态是 {{data_feed.order.status}}！

{% if data_feed.order.tracking_number != empty %}
在此跟踪：{{data_feed.order.tracking_url}}
{% endif %}
在这里，只有在 tracking_number 存在时才会显示跟踪链接。

​
无个性化的自动化

数据源可以用于自动向您的消息中插入最新信息，而不一定需要针对每个收件人进行个性化。 例如，也许您在电子邮件顶部插入横幅图像，并每月更改以跟上假期和其他月度活动。与其每月记得向 OneSignal 上传新图像并更改所有模板，您可能设置一个数据源，从您的 CMS 或其他资产管理位置获取当前横幅图像 URL。 您将设置一个 banner 数据源，指向一个 URL 中没有任何变量的端点，如下所示： 
https://acme.com/assets/email-banner
它返回当前横幅 URL 的响应：
JSON
{
	"banner_url": "https://acme.com/assets/email-banner/2025july.png"
}
您将设置您的电子邮件模板使用 {{ data_feed.banner.banner_url }} 作为图像源 URL，自动化此过程。

​
故障排除

​
我的数据没有显示

  1. 检查您的数据源是否附加到模板
  2. 验证您的 Liquid 语法是否与您的 JSON 结构完全匹配
  3. 手动测试您的 API 端点以确保它返回数据
  4. 检查用户是否具有所需的数据标签（如 external_id）

​
消息发送缓慢

  1. 检查您的 API 响应时间
  2. 确保您的 API 可以处理并发请求

​
某些收件人没有收到消息

  1. 您的 API 可能没有这些用户的数据
  2. 检查数据源配置中的错误日志，查找 404 或错误
  3. 检查您的 API 日志，查找 404 或错误
  4. 验证这些用户在 OneSignal 中具有所需的标识符