> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apache Kafka

> 从 Apache Kafka 主题同步自定义事件到 OneSignal，以基于实时用户行为触发自动化旅程和个性化消息传递活动。

export const PLATFORM_0 = "Kafka"

export const DATA_TYPE_0 = undefined

export const COLUMN_HEADER_0 = undefined

export const PROPERTIES_DESCRIPTION_0 = undefined

## 概览

OneSignal + Apache Kafka 集成支持将自定义事件从您的 Kafka 主题自动同步到 OneSignal 的自定义事件 API。这使您能够基于通过 Kafka 基础设施流式传输的实时用户行为触发自动化旅程和个性化消息传递活动。

您可以同步购买、产品浏览、订阅变更或任何自定义用户操作等事件，以自动触发引导序列、重新参与活动、交易消息和跨推送通知、电子邮件、应用内消息和短信的定向促销。

***

## 要求

* 访问自定义事件（目前处于测试阶段）
* [升级账户计划](https://onesignal.com/pricing)（免费应用不可用）。

### Apache Kafka

* **Kafka 集群**（Apache Kafka、Confluent 或云托管）
* 包含事件数据的**主题**
* **身份验证凭据**（SASL/SCRAM、SSL 或 API 密钥）
* 对 Kafka 代理的**网络访问**
* JSON 格式的**事件数据**

***

## 设置

### 配置 Kafka 权限

OneSignal 需要从您的 Kafka 主题消费事件。具体设置取决于您的 Kafka 配置：

<Steps>
  <Step title="收集连接详细信息">
    收集有关您 Kafka 集群的以下信息：

    * **引导服务器**：Kafka 代理端点
    * **安全协议**：PLAINTEXT、SASL\_PLAINTEXT、SASL\_SSL 或 SSL
    * **身份验证**：用户名/密码、证书或 API 密钥
    * **主题名称**：包含事件数据的主题列表
  </Step>

  <Step title="创建消费者凭据">
    为 OneSignal 创建访问您 Kafka 主题的凭据：

    **对于 SASL/SCRAM 身份验证：**

    ```bash theme={null}
    # 创建具有事件主题读取权限的用户
    kafka-configs --bootstrap-server localhost:9092 \
      --alter --add-config 'SCRAM-SHA-256=[password=onesignal-password]' \
      --entity-type users --entity-name onesignal-consumer
    ```

    **对于基于 ACL 的授权：**

    ```bash theme={null}
    # 授予主题和消费者组的读取权限
    kafka-acls --bootstrap-server localhost:9092 \
      --add --allow-principal User:onesignal-consumer \
      --operation Read --topic your-event-topic

    kafka-acls --bootstrap-server localhost:9092 \
      --add --allow-principal User:onesignal-consumer \
      --operation Read --group onesignal-consumer-group
    ```
  </Step>

  <Step title="验证主题访问">
    测试 OneSignal 是否可以访问您的事件主题：

    ```bash theme={null}
    kafka-console-consumer --bootstrap-server localhost:9092 \
      --topic your-event-topic \
      --from-beginning \
      --max-messages 5
    ```
  </Step>
</Steps>

### 配置 OneSignal Kafka 连接

<Steps>
  <Step title="导航到集成">
    在 OneSignal 中，前往 **数据 > 集成**，然后点击 **添加集成**。
  </Step>

  <Step title="选择 Apache Kafka">
    从可用集成列表中选择 **Apache Kafka**。
  </Step>

  <Step title="输入连接详细信息">
    提供您的 Kafka 连接信息：

    * **引导服务器**：逗号分隔的代理端点
    * **安全协议**：您集群的安全配置
    * **用户名/密码**：SASL 凭据（如适用）
    * **主题名称**：包含您事件数据的主题
    * **消费者组**：OneSignal 的唯一组 ID
  </Step>

  <Step title="测试连接">
    点击 **测试连接** 以验证 OneSignal 能够连接到您的 Kafka 集群并消费事件。
  </Step>
</Steps>

***

### 事件数据映射

将您的 {PLATFORM_0} {DATA_TYPE_0} 映射到 OneSignal 的自定义事件格式：

| OneSignal 字段  | {COLUMN_HEADER_0} | 描述                         | 必需 |
| ------------- | ----------------- | -------------------------- | -- |
| `name`        | `event_name`      | 事件标识符                      | 是  |
| `external_id` | `user_id`         | 用户标识符                      | 是  |
| `timestamp`   | `event_timestamp` | 事件发生时间                     | 否  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | 否  |

***

## 事件数据架构

您的 Kafka 事件消息应为 JSON 格式，并包含映射到 OneSignal 自定义事件结构的字段：

| Kafka 事件字段   | OneSignal 事件字段 | 描述 |
| ------------ | -------------- | -- |
| `event_type` |                |    |