跳转到主要内容
数据源让您在发送时直接从您的 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_id98765 将存储到 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 中具有所需的标识符

I