- 用户当前的奖励余额
- 最新订单状态
- 个性化产品推荐
数据源目前仅适用于通过 Journeys 发送的邮件消息。
需要其他渠道?填写这份简短调查。
数据源的工作原理
- 创建数据源 – 配置 OneSignal 如何连接到您的 API。
- 将数据源附加到消息模板。
- 使用 Liquid 语法在消息中插入响应字段。
- 在发送时,OneSignal 为每个收件人进行 API 调用,解析响应,并将数据注入到您的消息中。
示例:显示奖励积分
假设您想向每个客户显示他们的奖励余额:{{ data_feed.rewards.points }}
和 {{ data_feed.rewards.status_level }}
。
我们将使用这个示例在下面逐步向您展示如何设置数据源。
创建和使用数据源
1. 设置您的数据源配置
在侧边栏中导航至数据 > 数据源,查看现有数据源列表并创建新的数据源。 每个数据源必须具有:- 名称:描述性名称,如”客户奖励 API”,帮助您在数据源列表中区分它。我们建议这些名称是唯一的,但不是必需的。
- 别名:像 rewards 这样的简短名称,您将在 Liquid 语法中使用。这些必须是唯一的,不能包含空格,只能包含小写字母数字字符,没有特殊符号。
- 方法:我们应该如何联系您的 API。通常这是 GET,但也支持 POST。
- URL:API 的地址。您可以包含 Liquid 语法,使我们能够调用 API 来获取特定用户的数据。
- 标头:根据您的 API 规范需要输入标头键值对。一个典型的重要用途是包含身份验证信息。如果需要,这些字段也支持 Liquid 语法。
- 请求体:如果您的 API 需要,您可以在请求中包含 JSON 格式的请求体。此编辑器支持 Liquid 语法,就像 Journey Webhooks 一样。

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

个性化按钮选项
- 打开数据源并选择您的数据源

消息编辑器中的数据源部分
- 保存您的模板
3. 在消息中使用数据
使用 Liquid 语法在消息中的任何地方插入响应数据。在我们的示例中,假设对于 Sarah(其 external_id 是1a1-b2c3
)的响应是这样一个简单的 JSON 数据:
- 使用数据源
- 使用
rewards
数据源- 回忆:
rewards
数据源知道用收件人的external_id
调用 API
- 回忆:
- 从响应中,插入
points
项的值(193)和status_level
项的值(Gold)
要求和限制
您的 API 需要:- 接受单步身份验证,在标头中使用身份验证令牌
- 快速响应。 推荐在250毫秒以内(这直接影响发送速度)
- 返回JSON。 目前不支持其他格式。
- 如果您有依赖替代格式的用例,我们想听听您的意见!请在此填写简短调查。
- 处理您的消息发送量和频率。 如果您的 API 有较低的速率限制,这将阻止我们快速投递您的消息。
- 返回合理大小的负载。 我们建议保持响应在50kb以下以获得最佳性能。
- 每个模板一个数据源。 我们预计在未来增加此限制。在此填写简短调查,让我们知道您需要这个功能。
- 每个数据源每条消息一次 API 调用。 在一次调用中获取您需要的所有内容。
- 仅限 Journeys。 尚未适用于其他发送方法。在此填写简短调查,让我们知道您需要这个功能。
- 没有链式调用。 一个数据源的负载不能用于调用另一个数据源。
设置您的 API
在创建数据源之前,确保您的 API 能够处理这些要求:身份验证
您的 API 应通过标头接受身份验证:JSON 请求体
如果您需要在请求中包含请求体,您的 API 应接受 JSON。这可能意味着您的标头需要包含Content: application/json
。
JSON 响应
您的 API 应返回 JSON 对象。通常这意味着您的标头将包含Accept: application/json
。
个性化参数
您通常会在URL中传递用户标识符,如下所示:JSON
速率限制
考虑您的 API 速率限制。如果您快速连续向10,000个用户发送,我们将进行10,000次 API 调用。确保您的 API 能够处理这个数量。错误处理
如果您的 API 返回错误或没有用户数据,消息不会发送给该收件人。确保您的 API 为所有预期用户返回数据。入门清单
在实施数据源之前,请回答这些问题:- 我想在消息中显示什么数据?从简单的大纲开始,识别要从您的 API 填充的项目,这将帮助您组织思路。
- 这些数据是否可以通过单个 API 端点获得?
- 我将如何验证 API 请求?
- 我将使用什么标识符或其他数据项来获取个性化数据?
- 该标识符是否已经存储在 OneSignal 中?如果没有,将如何填充?
- 我的 API 能否处理我将产生的请求量?
- 如果我的 API 没有用户数据会怎样?
示例和高级用例
数据源可以与 Liquid 语法结合使用,或与其他功能创造性地结合使用,以产生更复杂的个性化。循环迭代:废弃购物车
假设您有一个数据源 cart,它返回用户购物车中的商品数组,以及购物车的总金额:JSON
HTML
如果您使用电子邮件块编辑器,当插入这种复杂的 Liquid 语法时,特别是如果您需要包含图像或链接,最好使用自定义 HTML 块元素以获得最佳结果。
自定义事件负载
继续上一个废弃购物车示例,我们首先如何知道要获取那个特定的购物车呢? 一种方法可能是创建一个由cart_abandoned
自定义事件 触发的 Journey,其中负载包含 cart_id。在此示例中,该事件通过 API 发送到 OneSignal:
curl

Journey 入口的自定义事件
user_12345
进入旅程,然后到达发送电子邮件的节点。该电子邮件模板使用 cart
数据源设置,其中 URL 设置为检索特定购物车的内容,如下所示:
cart_id
值98765
将存储到 Journey 中- 当到达电子邮件步骤时,
cart
数据源将引用该cart_id
值并使用它来调用购物车 API - 返回的 JSON 负载将被解析并插入到电子邮件中,如上面的前一个示例所示
条件显示:订单状态
假设您想包含客户订单的状态,但仅在订单已发货时包含跟踪号链接。您可以使用if
语句来做到这一点:
tracking_number
存在时才会显示跟踪链接。
无个性化的自动化
数据源可以用于自动向您的消息中插入最新信息,而不一定需要针对每个收件人进行个性化。 例如,也许您在电子邮件顶部插入横幅图像,并每月更改以跟上假期和其他月度活动。与其每月记得向 OneSignal 上传新图像并更改所有模板,您可能设置一个数据源,从您的 CMS 或其他资产管理位置获取当前横幅图像 URL。 您将设置一个banner
数据源,指向一个 URL 中没有任何变量的端点,如下所示:
JSON
{{ data_feed.banner.banner_url }}
作为图像源 URL,自动化此过程。
故障排除
我的数据没有显示
- 检查您的数据源是否附加到模板
- 验证您的 Liquid 语法是否与您的 JSON 结构完全匹配
- 手动测试您的 API 端点以确保它返回数据
- 检查用户是否具有所需的数据标签(如
external_id
)
消息发送缓慢
- 检查您的 API 响应时间
- 确保您的 API 可以处理并发请求
某些收件人没有收到消息
- 您的 API 可能没有这些用户的数据
- 检查数据源配置中的错误日志,查找 404 或错误
- 检查您的 API 日志,查找 404 或错误
- 验证这些用户在 OneSignal 中具有所需的标识符