事件流集成

需要开发人员协助

您需要开发团队的帮助来设置此集成。请与他们分享本指南。

集成概述

集成类型

源： 数据根据配置的事件触发器，通过 HTTP 或 gRPC 从 Pushwoosh 发送到您的系统。

集成如何工作？

Pushwoosh 将通信事件数据（例如，推送/电子邮件活动）传输到客户端定义的端点。数据以批处理流的形式在预定时间间隔或达到最小批处理大小时发送。

只有当数据与所选事件、平台和可选过滤器（营销活动/消息代码、实时活动）匹配时，才会发送数据。客户端端点必须准备好接收并可选择性地响应状态。

术语表

端点 URL：允许接收请求的服务器端端点。客户端可以根据需要指定端口。

示例：

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook_endpoint

同步实体列表

• 通信统计事件（例如，Push Sent、Email Delivered）
• Post events：您的应用通过 postEvent 发送到 Pushwoosh 的事件，与通信统计事件分开流式传输

用例

• 实时互动跟踪

  实时监控用户互动，如推送发送、邮件打开或消息送达，从而即时了解营销活动效果。

• 外部分析集成

  将事件流式传输到第三方分析平台，以进行集中报告和分析。

• 自动化用户工作流

  根据用户行为在外部系统（如 CRM 或营销自动化工具）中触发操作，例如，当用户打开电子邮件时发送后续消息。

设置集成

要设置集成：

1. 在您的 Pushwoosh 账户中，前往 Settings > 3rd party Integrations，找到 Event streaming integration，然后点击 Configure。

2. 在打开的窗口中，填写必要的字段。

输入端点 URL

在 Endpoint URL 字段中，输入将发送事件的完整 URL，如果适用，请包括协议和端口。

示例

• https://clientdomainname.com/webhook_endpoint
• https://clientdomainname.com:8081/webhook\_endpoint

选择事件

从 Events 下拉菜单中，至少选择一个事件。如果未选择任何事件，验证将失败。事件列表由后端管理，可能会随时间变化。

提供授权凭证

如果您的服务器需要，请在 Authorization 字段中输入 Authorization 标头的完整值。

示例：

• Bearer your_token_here

• Basic base64encoded_credentials

注意

该值将 按原样 插入到 Authorization 标头 (HTTP) 或 gRPC 元数据中。请确保身份验证方案和令牌之间有一个空格。

选择传输类型

从 Transport type 下拉菜单中，选择事件传输的交付协议：HTTP 或 gRPC。每种协议都有特定的行为和配置。

HTTP

使用 HTTP 传输类型时，Pushwoosh 会根据以下条件之一批量发送数据：

• 至少有 100 个事件准备好发送，或者

• 自上次传输以来已过去一小时。

发送数据后，一旦收到成功响应，连接即关闭。

如果服务器响应 5xx 错误，Pushwoosh 将根据定义的重试策略重试请求。

重试机制

尝试次数	延迟
第 1 次	1 秒
第 2 次	第 1 次尝试后 3 秒
第 3 次	第 2 次尝试后 8 秒

如果所有重试都失败，请求将被丢弃。

超时

请求的默认超时时间为 30 秒。这可以通过支持请求进行自定义。

查看示例

gRPC

gRPC 传输类型使用 双向流 进行数据传输。更多信息请参阅 gRPC 文档。

当满足以下任一条件时，将打开一个流：

• 至少有 1,000 个事件准备好交付
• 自上次打开流以来已过去一小时

事件发送后，流将关闭。这确保了在短时间内不会为每个单独的事件打开新流。

查看 protobuf 规范

重试机制
每个事件都包含一个唯一的 uuid。如果事件失败：

1. 响应必须包含一个 不等于 "Success" 的 status
2. 必须包含请求中的原始 uuid

Pushwoosh 将根据此响应重试交付。

连接设置

高级选项如 TLS、keep-alive 或 重试策略 需要通过支持手动配置，并可能需要开发人员参与。

启用 post 事件

此开关默认关闭，因此只有通信统计事件会流式传输。要同时流式传输您的应用通过 postEvent 发送到 Pushwoosh 的事件，请打开 Allow post events 开关。

在出现的 Post events 字段中，选择要流式传输的您账户中的事件。当开关打开时，至少需要一个事件。如果您的账户尚未发送任何事件，此列表将为空，直到您至少调用一次 postEvent。

注意

Post events 会发送到上面输入的相同 Endpoint URL，并且无论平台如何都会到达该 URL：下面的 Platforms 和 Advanced filters 部分仅适用于通信统计事件，不适用于 post events。

选择平台

在 Platforms 部分，至少选择一个平台以激活事件流。

支持的平台包括：

• iOS, Android, macOS, Windows, Amazon, Safari
• Chrome, Firefox, Internet Explorer, Huawei
• Email, SMS, Line, Xiaomi, WhatsApp

配置高级过滤器

在 Advanced filters 部分，使用过滤器优化事件交付标准：

• 实时活动事件： 启用以接收实时活动事件。这些事件仅包含元数据，包括 live_activity_id。

• 营销活动过滤器： 按营销活动代码过滤。只有与这些营销活动相关的事件才会被交付。

• 消息过滤器： 按消息代码过滤。只有与这些消息相关的事件才会被交付。

完成所有必填字段后，点击 Apply 按钮保存并激活您的集成。

注意

配置更改将在提交后 15 分钟内 生效。

提示

有关高级设置，如自定义超时或 gRPC 配置，请联系支持。

请求详情和示例

端点	https://exampleclientendpoint.com/webhook_endpoint
HTTP 请求	POST
身份验证	无
请求类型	源
请求含义	向 webhook 端点发送请求
标头	Content-Type: application/json

请求正文示例

{
  "event_name": "Email Opened",
  "message_code": "E682-E6D92B9A-53E24868",
  "campaign_id": 961048,
  "platform": "Email",
  "payload": "Welcome to Headway! 👋",
  "application_code": "XXXXX-XXXXX",
  "hwid": "user@example.com",
  "user_id": "USER_ID",
  "timestamp": 1723799271,
  "journey_title": "",
  "journey_point_title": "5_Welcome_ID_new",
  "attributes": null
}

属性

在通信统计事件中，attributes 仅针对推送事件填充，内容为推送发送平台的渠道特定内容（Android、iOS 等）。电子邮件和短信事件仅携带顶级字段（event_name、platform、payload 等）。对于这些事件，attributes 为 null。在已填充的 attributes 对象中，事件自身平台之外的字段会被省略，而不会作为空值发送。请参阅 webhook.proto 获取完整字段列表。

post 事件则将其属性键/值对携带在 attributes.event_attributes 中。message_code 和 payload 保持为空，因为 post 事件与消息或营销活动无关。

警告

attributes.geozone 已弃用：源属性是一个对象，而不是一个数字，因此该字段从未携带过真实值。请改为从 attributes.geozone_data 读取实际的地理区域。旧字段保留在合同中，以供具有现有 gRPC 存根的客户端使用。

响应
目前，响应代码和正文将被忽略。

如何判断集成是否正常工作？

您将开始在您配置的端点接收来自 Pushwoosh 的请求。