> ## 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로 커스텀 이벤트를 동기화하여 실시간 사용자 행동을 기반으로 자동화된 Journey 및 개인화된 메시징 캠페인을 트리거합니다.

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 인프라를 통해 스트리밍되는 실시간 사용자 행동을 기반으로 자동화된 Journey 및 개인화된 메시징 캠페인을 트리거할 수 있습니다.

구매, 제품 보기, 구독 변경 또는 모든 커스텀 사용자 작업과 같은 이벤트를 동기화하여 푸시 알림, 이메일, 인앱 메시지 및 SMS를 통해 온보딩 시퀀스, 재참여 캠페인, 트랜잭션 메시지 및 타겟 프로모션을 자동으로 트리거할 수 있습니다.

***

## 요구 사항

* Access to [Event Streams](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (not available on free apps)

### Apache Kafka

* **Kafka 클러스터**(Apache Kafka, Confluent 또는 클라우드 관리형)
* 이벤트 데이터가 포함된 **토픽**
* **인증 자격 증명**(SASL/SCRAM, SSL 또는 API 키)
* Kafka 브로커에 대한 **네트워크 액세스**
* JSON 형식의 **이벤트 데이터**

***

## 설정

### Kafka 권한 구성

OneSignal은 Kafka 토픽에서 이벤트를 소비해야 합니다. 정확한 설정은 Kafka 구성에 따라 다릅니다:

<Steps>
  <Step title="연결 세부 정보 수집">
    Kafka 클러스터에 대한 다음 정보를 수집합니다:

    * **Bootstrap 서버**: Kafka 브로커 엔드포인트
    * **보안 프로토콜**: PLAINTEXT, SASL\_PLAINTEXT, SASL\_SSL 또는 SSL
    * **인증**: 사용자 이름/비밀번호, 인증서 또는 API 키
    * **토픽 이름**: 이벤트 데이터가 포함된 토픽 목록
  </Step>

  <Step title="컨슈머 자격 증명 생성">
    OneSignal이 Kafka 토픽에 액세스할 수 있도록 자격 증명을 생성합니다:

    **SASL/SCRAM 인증의 경우:**

    ```bash theme={null}
    # Create a user with read access to event topics
    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}
    # Grant read access to topics and consumer group
    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에서 **Data > Integrations**으로 이동하여 **Add Integration**을 클릭합니다.
  </Step>

  <Step title="Apache Kafka 선택">
    사용 가능한 통합 목록에서 **Apache Kafka**를 선택합니다.
  </Step>

  <Step title="연결 세부 정보 입력">
    Kafka 연결 정보를 제공합니다:

    * **Bootstrap 서버**: 쉼표로 구분된 브로커 엔드포인트
    * **보안 프로토콜**: 클러스터의 보안 구성
    * **사용자 이름/비밀번호**: SASL 자격 증명(해당하는 경우)
    * **토픽 이름**: 이벤트 데이터가 포함된 토픽
    * **컨슈머 그룹**: OneSignal의 고유 그룹 ID
  </Step>

  <Step title="연결 테스트">
    **연결 테스트**를 클릭하여 OneSignal이 Kafka 클러스터에 연결하고 이벤트를 소비할 수 있는지 확인합니다.
  </Step>
</Steps>

***

### 이벤트 데이터 매핑

{PLATFORM_0} {DATA_TYPE_0}를 OneSignal의 사용자 지정 이벤트 형식에 매핑합니다:

| OneSignal 필드  | {COLUMN_HEADER_0} | 설명                         | 필수  |
| ------------- | ----------------- | -------------------------- | --- |
| `name`        | `event_name`      | 이벤트 식별자                    | Yes |
| `external_id` | `user_id`         | 사용자 식별자                    | Yes |
| `timestamp`   | `event_timestamp` | 이벤트가 발생한 시간                | No  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | No  |

***

## 이벤트 데이터 스키마

Kafka 이벤트 메시지는 JSON 형식이어야 하며 OneSignal 커스텀 이벤트 구조에 매핑되는 필드를 포함해야 합니다:

| Kafka 이벤트 필드 | OneSignal 이벤트 필드 | 설명 |
| ------------ | ---------------- | -- |
| `event_type` |                  |    |