# 事件流集成
## 集成概述
### 集成类型
**源：** 数据根据配置的事件触发器，通过 HTTP 或 gRPC 从 Pushwoosh 发送到您的系统。
### 集成如何工作？
Pushwoosh 将通信事件数据（例如，推送/电子邮件活动）传输到客户端定义的端点。数据在预定时间间隔或达到最小批次大小时以批量流的形式发送。
只有当数据与所选事件、平台和可选筛选器（营销活动/消息代码、实时活动）匹配时，才会发送数据。客户端端点必须准备好接收并可选择性地以状态响应。
### 术语表
**端点 URL**：允许接收请求的服务器端端点。客户端可以根据需要指定端口。
示例：
* `https://clientdomainname.com/webhook_endpoint`
* `https://clientdomainname.com:8081/webhook_endpoint`
### 同步实体列表
* 通信统计事件（例如，Push Sent、Email Delivered）
### 用例
* **实时互动跟踪**
实时监控用户互动，如推送发送、电子邮件打开或消息送达，从而能够即时了解营销活动的效果。
* **外部分析集成**
将事件流式传输到第三方分析平台，以进行集中报告和分析。
* **自动化用户工作流**
根据用户行为在外部系统（如 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`
#### 选择传输类型
从 **Transport type** 下拉菜单中，选择事件传输的交付协议：**HTTP** 或 **gRPC**。每种协议都有特定的行为和配置。
##### HTTP
使用 **HTTP** 传输类型，Pushwoosh 会根据以下任一条件批量发送数据：
* 至少有 100 个事件准备好发送，或者
* 自上次传输以来已过去一小时。
发送数据后，一旦收到成功响应，连接即关闭。
如果服务器响应 **5xx 错误**，Pushwoosh 将根据定义的重试策略重试请求。
**重试机制**
| 尝试次数 | 延迟 |
| :---- | :---- |
| 第 1 次 | 1 秒 |
| 第 2 次 | 第一次尝试后 3 秒 |
| 第 3 次 | 第二次尝试后 8 秒 |
如果所有重试都失败，请求将被丢弃。
**超时**
请求的默认超时时间为 **30 秒**。这可以通过支持团队根据请求进行自定义。
##### gRPC
gRPC 传输类型使用 **双向流** 进行数据传输。更多信息请参阅 [gRPC 文档](https://grpc.io/docs/what-is-grpc/core-concepts/#bidirectional-streaming-rpc)。
当满足以下任一条件时，将打开一个流：
* 至少有 1,000 个事件准备好交付
* 自上次打开流以来已过去一小时
事件发送后，流将关闭。这确保了在短时间内不会为每个单独的事件打开新流。
**重试机制**
每个事件都包含一个唯一的 `uuid`。如果事件失败：
1. 响应必须包含一个 **不等于** `"Success"` 的 `status`
2. 必须包含请求中的原始 `uuid`
Pushwoosh 将根据此响应重试交付。
**连接设置**
高级选项如 **TLS**、**keep-alive** 或 **重试策略** 需要通过支持团队手动配置，并可能需要开发人员参与。
### 选择平台
在 **Platforms** 部分，至少选择一个平台以激活事件流。
支持的平台包括：
* iOS、Android、macOS、Windows、Amazon、Safari
* Chrome、Firefox、Internet Explorer、Baidu、Huawei
* Email、SMS、Line、Xiaomi、WhatsApp
### 配置高级筛选器
在 **Advanced filters** 部分，使用筛选器优化事件交付标准：
* **实时活动事件：** 启用以接收实时活动事件。这些事件仅包含元数据，包括 `live_activity_id`。
* **营销活动筛选器：** 按营销活动代码筛选。只有与这些营销活动相关的事件才会被交付。
* **消息筛选器：** 按消息代码筛选。只有与这些消息相关的事件才会被交付。
完成所有必填字段后，点击 **Apply** 按钮保存并激活您的集成。
## 请求详情和示例
| | |
|-----------------------|----------------------------------------------------------|
| **端点** | `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"
}
```
**响应**
目前，响应代码和正文将被忽略。
## 如何知道集成是否正常工作？
您将开始在您配置的端点上接收来自 Pushwoosh 的请求。