跳转到主要内容
事件流允许您将消息数据实时从 OneSignal 发送到您选择的目标。事件流是将 OneSignal 连接到营销生态系统中其他产品的绝佳方式。它们使您的团队能够触发相应的消息传递、维护记录等等。

​
常见用例

  1. 客户旅程映射和个性化：将事件流传输到 CRM 或客户数据平台 (CDP) 以构建全面的客户档案，并在各个触点定制活动。
  2. 分析和报告：将消息事件（例如发送、打开、点击）发送到数据仓库，以分析参与模式或跨渠道的长期趋势。
  3. 合规和监管报告：将所有消息发送数据流传输到数据仓库用于审计和合规目的。
  4. AI 和预测模型：将消息事件数据发送到内部 AI 或预测模型，以创建全面的客户群体并了解流失风险——例如邮件取消订阅或消息关闭，这可能表明潜在的流失。
  5. 营销自动化：将参与事件（如消息打开或点击）发送到其他工具，以自动触发用户旅程中的下一步骤或更新客户档案和最近活动。
  6. 数据碎片化：有价值的客户数据通常分散在不同的工具中（如客户参与平台、CRM、分析工具和数据仓库）。事件流有助于集中这些数据，提高对有价值第一方数据的可见性，并实现更快的收入成果。
  7. 系统间通信缓慢：通过将实时参与事件发送到其他系统，您可以在事件发生后立即触发操作，而不是等待数小时或数天的批量更新。这消除了对手动导入或数据同步的依赖。
  8. 支出膨胀和技术债务：您可以直接将 OneSignal 与数据仓库连接，而不是管理多个中间工具。这减少了管理多个集成或自定义数据管道的昂贵开销，减少了技术债务，并为产品和营销保留了宝贵的技术资源。

​
如何与技术团队合作

设置事件流需要与您的技术团队合作。以下是促进对话的一些技巧：
  1. 解释好处：分享您使用此数据的策略，以及它如何增强营销活动、个性化用户体验、整合数据并减少技术债务。
  2. 定义范围：确定您希望将数据发送到何处、您想跟踪哪些事件以及估计的数据量。这将有助于配置正确的端点设置。
  3. 提供技术文档：分享 OneSignal 的技术文档和设置说明。您的开发团队需要配置接收端点和 OneSignal 中的事件流，确保数据正确路由。
  4. 讨论数据量和管理：确认您的系统可以处理实时数据流。建议 API 处理程序在不进行额外在线处理的情况下记录事件，以保持低响应时间。
  5. 测试和故障排除：在上线之前进行测试，确保一切运行顺利。
通过与技术团队密切合作，您可以释放事件流的力量来增强您的增长策略。

​
设置

您可以在数据 > 事件流下为您的 OneSignal 应用程序配置新的事件流。

​
要求

除非满足以下要求，否则无法发送事件：
  • 指向您的服务器 HTTP(S) 服务器的有效 URL 或 IP 地址
  • URL 和 IP 地址必须可公开路由
  • 域名必须包含已识别的顶级域名（例如”.com”、“.net”）

​
事件选择

点击”选择事件”来选择您希望触发事件流的事件。

触发 Webhook

这些事件发送的数据非常相似，您可以通过同一个事件流发送由多个渠道触发的事件。另一种方法是为单个渠道或事件定义多个事件流，以实现更精细的控制或减少发送的数据规模。

事件选择

​
事件流过滤器

您可以通过指定一个或多个消息或模板的标识符来进一步优化事件，使您只接收与应用程序中特定消息相关的事件。请参考以下说明启用事件流过滤。

按模板过滤事件

消息和模板标识符可以通过导航到消息 > 推送、电子邮件、短信或模板，点击所需消息或模板的操作按钮，然后从操作菜单中选择复制消息ID或复制模板ID来复制。

复制模板的模板 ID

或者，您可以直接从 URL 复制您正在查看的消息/模板标识符：
  • 模板 – https://dashboard.onesignal.com/apps/{APP_ID}/templates/{TEMPLATE_ID}
  • 推送 – https://dashboard.onesignal.com/apps/{APP_ID}/notifications/{MESSAGE_ID}
  • 电子邮件 – https://dashboard.onesignal.com/apps/{APP_ID}/email/{MESSAGE_ID}
  • 短信 – https://dashboard.onesignal.com/apps/{APP_ID}/sms/{MESSAGE_ID}

​
配置事件流

选择 HTTP 方法、URL，并为事件流添加头部。这是应该配置身份验证的地方，以确保 OneSignal 和您的系统之间的安全通信。 URI 和头部可以包含 liquid 语法，这些语法来自用户属性和事件流的属性。

​
认证头部

您可以添加认证头部来验证发送到您端点的请求确实来自 OneSignal。常见的认证方法包括：
  • 授权头部：添加一个 Authorization 头部，其中 YOUR_TOKEN 由您的系统或第三方提供，如：
    • Basic {{YOUR_TOKEN}}
    • Bearer {{YOUR_TOKEN}}
    • ApiKey {{YOUR_API_KEY}}
  • 自定义头部：您也可以添加自定义头部，如：
    • X-API-Key: {{YOUR_API_KEY}}
注意：OneSignal 不提供加密服务

​
测试您的配置

如果您正在寻找一种简单的测试方法，请使用 webhook.site。在页面中央找到”您的唯一 URL”。复制该 URL 并在您的事件流配置的 URL 字段中使用它。

配置 Webhook

​
禁用的头部

以下头部是受限的，无法设置。
  • content-length
  • referer
  • metadata-flavor
  • x-google-metadata-request
  • host
  • x-onesignal*

​
正文

事件流的正文将是 JSON 格式。正文 JSON 可以定义为单独的键/值对，也可以定义为可编辑的代码块。要更改输入方法，请使用正文标题下的第一个下拉菜单并选择自定义正文。

事件流正文选项

在右侧，您可以看到根据事件流设置期间输入的内容构建的示例 cURL 请求

事件流的 cURL 预览

​
个性化

您可以使用预定义的事件流数据个性化事件流中的所有字段。可以使用 Liquid 语法添加此数据。这为您使用事件流应对几乎任何用例提供了灵活性。
查看事件流数据了解所有可用于个性化的事件、消息和用户事件数据列表。

​
示例正文

在下拉菜单中选择”自定义正文”： 
{
  "Event Data": {
    "event.kind": "{{ event.kind }}",
    "event.id": "{{ event.id }}",
    "event.timestamp": "{{ event.timestamp }}",
    "event.datetime": "{{ event.datetime }}",
    "event.app_id": "{{ event.app_id }}",
    "event.subscription_device_type": "{{ event.subscription_device_type }}",
    "event.subscription_id": "{{ event.subscription_id }}",
    "event.onesignal_id": "{{ event.onesignal_id }}",
    "event.external_id": "{{ event.external_id }}"
  },
  "Message Data": {
    "message.id": "{{ message.id }}",
    "message.name": "{{ message.name }}",
    "message.title": "{{ message.title.en }}",
    "message.contents": "{{ message.contents.en }}",
    "template_id": "{{ message.template_id }}",
    "message.template_id": "{{ message.template_id }}",
    "message.url": "{{ message.url }}",
    "message.app_url": "{{ message.app_url }}",
    "message.web_url": "{{ message.web_url }}"
  }
}

自定义正文

​
在 JSON 中使用 Liquid 语法

在 JSON 中使用 Liquid 语法时，正确的引用取决于数据类型： JSON 格式化指南
  • 字符串 → 必须用引号包围。
  • 数字 → 不要用引号包围。
  • 对象 → 必须不用引号包围。
示例

​
字符串

✅ 正确 
// 用引号包围字符串值
{
  "user_id": "{{ user.onesignal_id }}"
}
❌ 错误 
{
  "user_id": {{ user.onesignal_id }}
}

​
数字和布尔值

✅ 正确 
// 不要用引号包围数字或布尔值
{
  "user_score": {{ user.tags.score }}
}
❌ 错误 
{
  "user_score": "{{ user.tags.score }}"
}

​
对象

✅ 正确 
// 不要用引号包围对象。
{
  "user_data": {{ user.tags }}
}
❌ 错误 
{
  "user_data": "{{ user.tags }}"
}
在 liquid 语法中处理多语言条件语句的最佳实践 为避免基于语言的条件语句问题
  1. 使用直接语言检查：在条件语句中始终直接检查 user.language，而不是在变量（如 userLang）中检查，以获得更好的兼容性。
  2. 从简单开始：从基本短语开始，然后逐渐增加复杂性。
  3. 避免过度嵌套：保持条件语句扁平化以防止解析问题。
  4. 首先测试基本标点符号：在使用特殊字符之前，先使用简单句子和标点符号开始。
  5. 使用回退机制：确保在缺少翻译的情况下有默认语言（例如英语）。
  6. 坚持使用标准键：使用标准 OneSignal 键（如 content/title/en）以确保可靠性。
这种方法可以最大限度地减少解析错误并确保与系统的兼容性。
有关如何使用 Liquid 语法个性化消息的详细信息和选项，请查看我们的使用 Liquid 语法指南。

​
结果与调试

您可以在报告选项卡下的事件流报告页面上查看事件流在一段时间内的性能。这将包括历史数据、事件流的当前状态以及显示 hook 接收到的响应类型的时序数据。200 范围内的任何 HTTP 响应表示事件已成功接收，而 400 和 500 范围内的响应表示错误。超时意味着对方服务器未能在合理时间内响应，因此 OneSignal 关闭了连接并认为其失败。 您可以在日志选项卡下查看最近请求的样本以获得更多详细信息。这将显示实际请求和对方的响应（如果适用）。如果您的事件流有问题，这是首先查看的地方。如果您需要更改/更新事件流，可以在表单页面上编辑它并发送测试请求，以查看所需的完整详细信息，直到您能够正确设置。

事件流日志和指标

​
重试/禁用

当事件流请求因任何可恢复原因（例如状态码 429）失败时，OneSignal 将在短暂延迟后重试发送事件。这会发生几次，请求之间的延迟会越来越长。如果连续多次重试失败，该 hook 将被标记为”永久失败”，不再重试。 如果连续太多单独的请求失败，这可能是因为接收端存在问题；接收端可能有错误或已更改/禁用了某些内容。OneSignal 将继续发送请求到一定程度，但如果请求继续失败，事件流可能会被 OneSignal 禁用。如果发生这种情况，请务必花时间排除故障、修复，然后在重新启用之前测试事件流。 性能不佳的 API 可能导致事件流被禁用。重要的是，摄取事件流的 API 能够处理消息发送产生的事件量。审查应用程序产生的消息发送量将反映 API 所需的性能。 我们建议接收事件流的 API 记录事件而不进行任何其他在线处理。这将保持低响应时间并防止任何与延迟相关的问题。来自您 API 的缓慢响应时间或状态码 429 响应可能导致事件积压。持续的事件积压将导致 OneSignal 禁用事件流，以便您可以更新 API 以处理所需的吞吐量。 当事件流开始遇到大量失败事件（但尚未被禁用）时，以及当太多事件发送失败导致事件流被禁用时，OneSignal 将向应用管理员和组织管理员发送电子邮件。事件流索引页面上还将出现横幅，通知 OneSignal 用户其事件流之一存在问题。 每个事件流的每个事件都有唯一的 event.id。这可以用作头部或消息正文中的一种方式来检查并可能对重复的请求进行去重，如果您看到相同的请求进来的话。

​
成功提示

  1. 您通常希望事件流连接到您自己的服务器，而不是第三方服务。
    1. 虽然直接连接第三方没有问题，但以下内容可能更难管理：配置/调试将更具挑战性
    2. 请求量不会在 OneSignal 中管理。
      1. 事件流事件将在用户完成旅程中的步骤时快速发送，这可能会压垮其他服务、触及速率限制或意外增加您的费用。当尝试将另一个消息渠道用于短信等功能时，这种情况尤其常见。事件流的灵活性意味着 OneSignal 不知道您想用它们实现什么，因此您可能想要创建一个简单的自己的服务来接受事件流请求，然后正确处理您的第三方连接限制、速率限制和队列。
  2. 许多服务都有公共 HTTP API，这意味着您可以通过事件流连接到它们；查找它们的 API 文档和如何发出 HTTP 请求的示例以找到正确的入门位置。

​
测试

使用 https://webhook.site/ 等工具，并将提供的您的唯一 URL 设置到事件流中的 URL 参数，使用 POST 方法。

URL 匹配来自 webhook.site 的"您的唯一 URL"

设置您想要跟踪的事件。在此示例中，我们将使用推送事件，但任何事件都可以。

选择了推送消息事件，但任何事件都可以用于测试。

在此示例中，我们将使用上述示例正文。 保存事件并将其设置为生效。 发送消息以触发事件。在 webhook.site 中，我们将看到包含以下数据的事件：

使用 webhook.site 的示例

这显示了以下内容：
  • 主机：请求来源的 IP 地址。请参阅 REST API 概述了解可能的 IP 列表。
  • 请求内容：在事件流正文中发送的数据。