事件流

• 推送消息事件（已发送、已接收、已点击、失败、已取消订阅）
• 邮件事件（已发送、已打开、已点击、已退回、已取消订阅等）
• 短信事件（已发送、失败、已取消订阅等）
• 应用内消息事件（展示、已点击等）
• 实时活动事件（已发送、已投递、确认投递、失败、已取消订阅、已点击）

​

常见用例

• 集中参与数据 — 将事件流传输到 CRM、CDP 或数据仓库，使跨渠道活动（打开、点击、退回）集中存放在一处，而不是分散在各个独立工具中。
• 分析、报告与合规 — 将每条消息事件落地到数据仓库，用于趋势分析、审计或法规记录保存。
• 监控用户流失 — 在自有系统中跟踪取消订阅、退回和关闭事件，尽早发现用户留存风险。
• 触发外部工作流 — 当用户打开或点击消息时，在其他工具中触发自动化（例如更新潜在客户评分、启动跟进序列）。
• 替代批量同步和额外集成 — 实时响应事件，将 OneSignal 直接连接到目标，减少中间工具和维护成本。

​

让技术团队快速上手

1. 确定目标和范围 — 商定事件应落地的位置（自有 API、数据仓库、CDP 等）、要流传输的事件类型（推送、邮件、短信、IAM、实时活动）以及消息量估算，以便对端点进行适当的容量规划。
2. 设置 HTTP 端点 — 构建或配置可公开访问的端点，接受 POST 请求。它应快速记录事件，无需繁重处理，以保持低响应时间。请参阅重试/禁用了解性能预期以及端点落后时会发生什么。
3. 在 OneSignal 中配置事件流 — 在数据 > 事件流中，选择事件、设置 URL 和身份验证标头，并使用事件流数据字段和 Liquid 语法定义 JSON 正文。
4. 端到端测试 — 使用 webhook.site 在切换到生产端点之前验证有效载荷结构和标头（请参阅测试）。

​

设置

• 指向可公开访问的 HTTP(S) 端点的有效 URL 或 IP 地址
• URL 和 IP 地址必须可公开路由
• 域名必须包含已识别的顶级域名（例如”.com”、“.net”）

​

事件选择

​

事件流过滤器

​

配置事件流

​

认证头部

• 授权头部：添加一个 Authorization 头部，其中 YOUR_TOKEN 由您的系统或第三方提供，如：
  • Basic {{YOUR_TOKEN}}
  • Bearer {{YOUR_TOKEN}}
  • ApiKey {{YOUR_API_KEY}}
• 自定义头部：您也可以添加自定义头部，如：
  • X-API-Key: {{YOUR_API_KEY}}

​

测试您的配置

​

禁用的头部

• content-length
• referer
• metadata-flavor
• x-google-metadata-request
• host
• x-onesignal*

​

正文

​

个性化

​

示例正文

{
  "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 }}",
    "event.data.page_name": "{{ event.data.page_name}}",
    "event.data.page_id": "{{ event.data.page_id}}",
    "event.data.target_name": "{{ event.data.target_name}}",
    "event.data.target_id": "{{ event.data.target_id}}",
    "event.data.failure_reason": "{{ event.data.failure_reason}}"
  },
  "Message Data": {
    "message.id": "{{ message.id }}",
    "message.name": "{{ message.name }}",
    "message.title": "{{ message.title.en }}",
    "message.contents": "{{ message.contents.en }}",
    "message.template_id": "{{ message.template_id }}",
    "message.url": "{{ message.url }}",
    "message.app_url": "{{ message.app_url }}",
    "message.web_url": "{{ message.web_url }}"
  }
}

​

在 JSON 中使用 Liquid 语法

• 字符串 → 必须用引号包围。
• 数字 → 不要用引号包围。
• 对象 → 必须不用引号包围。

{
  "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 }}"
}

1. 使用直接语言检查：在条件语句中始终直接检查 user.language，而不是在变量（如 userLang）中检查，以获得更好的兼容性。
2. 从简单开始：从基本短语开始，然后逐渐增加复杂性。
3. 避免过度嵌套：保持条件语句扁平化以防止解析问题。
4. 首先测试基本标点符号：在使用特殊字符之前，先使用简单句子和标点符号开始。
5. 使用回退机制：确保在缺少翻译的情况下有默认语言（例如英语）。
6. 坚持使用标准键：使用标准 OneSignal 键（如 content/title/en）以确保可靠性。

​

结果与调试

​

重试/禁用

1. 当失败量达到一定程度（禁用前）以及流被禁用时，应用和组织管理员都会收到电子邮件通知。
2. 仪表板中的事件流索引页面上也会出现横幅。
3. 修复根本问题，使用日志选项卡或 webhook.site 进行测试，然后重新启用流。

• 快速记录事件 — 将传入事件写入队列或数据存储，无需进行繁重的内联处理。
• 避免响应缓慢和 429 — 持续的慢响应时间或速率限制响应会导致事件积压，进而导致 OneSignal 禁用流。
• 根据发送量进行容量规划 — 如果您发送 10 万条消息，则每个选定事件类型最多预计产生 10 万个事件。请查看您的计划消息量并据此进行规划。

​

成功提示

• 优先将流指向自己的服务器。 您可以直接连接到第三方 API，但当您不控制接收端时，调试、速率限制处理和用量管理会更加困难。
• 在转发给第三方之前进行缓冲。 OneSignal 以用户触发事件的速度发送——大量发送可能产生一次性流量冲击，压垮外部速率限制或增加费用（尤其是 SMS 提供商）。构建一个轻量级服务来接受事件、将其加入队列，然后以您控制的节奏转发给外部 API。
• 查看第三方 API 文档。 许多服务提供您可以通过事件流访问的公开 HTTP API。在配置流之前，查找其关于身份验证、接受的有效载荷格式和速率限制的文档。

​

消息事件数据限制

​

测试

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