> ## 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.

# Confluent Cloud

> Confluent Cloud에서 OneSignal로 사용자 지정 이벤트를 동기화하여 실시간 사용자 행동을 기반으로 자동화된 Journeys 및 개인화된 메시징 캠페인을 트리거합니다.

export const PLATFORM_0 = "Confluent Cloud"

export const DATA_TYPE_0 = undefined

export const COLUMN_HEADER_0 = undefined

export const PROPERTIES_DESCRIPTION_0 = undefined

## 개요

OneSignal + Confluent Cloud 통합을 사용하면 관리형 Kafka 토픽에서 OneSignal로 사용자 지정 이벤트를 자동으로 동기화할 수 있습니다. 이를 통해 Confluent Cloud 스트리밍 플랫폼을 통해 흐르는 실시간 사용자 행동 데이터를 기반으로 자동화된 Journeys 및 개인화된 메시징 캠페인을 트리거할 수 있습니다.

***

## 요구 사항

* 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)

### Confluent Cloud

* 활성 토픽이 있는 **Confluent Cloud 클러스터**
* 이벤트 토픽에 대한 읽기 액세스 권한이 있는 **API 자격 증명**
* **스키마 레지스트리** (구조화된 이벤트 스키마용 선택 사항)
* 적절한 메시지 형식으로 행동 데이터를 포함하는 **이벤트 토픽**

***

## 설정

<Steps>
  <Step title="Confluent Cloud에서 API 자격 증명 만들기">
    Confluent Cloud 콘솔에서 OneSignal용 API 자격 증명을 생성하세요:

    1. Confluent Cloud에서 **Data Integration > API Keys**로 이동하세요
    2. **Create key**를 클릭하고 **Global access**를 선택하세요
    3. **API Key** 및 **API Secret**을 저장하세요(OneSignal에 필요함)
    4. 클러스터 설정에서 **Bootstrap servers** 엔드포인트를 기록하세요
  </Step>

  <Step title="토픽 ACL 구성 (세분화된 권한 사용 시)">
    이벤트 데이터를 포함하는 특정 토픽에 대한 OneSignal 읽기 액세스 권한을 부여하세요:

    ```bash theme={null}
    confluent kafka acl create \
      --allow \
      --service-account <ONESIGNAL_SERVICE_ACCOUNT_ID> \
      --operation READ \
      --topic <EVENT_TOPIC_NAME>

    confluent kafka acl create \
      --allow \
      --service-account <ONESIGNAL_SERVICE_ACCOUNT_ID> \
      --operation DESCRIBE \
      --topic <EVENT_TOPIC_NAME>
    ```
  </Step>

  <Step title="OneSignal에서 통합 추가">
    OneSignal에서 **Data > Integrations**으로 이동하여 **Add Integration**을 클릭합니다.

    **Confluent Cloud**를 선택하고 다음을 제공하세요:

    * **Bootstrap Servers**: Confluent Cloud 클러스터 엔드포인트
    * **API Key**: Confluent Cloud API 키
    * **API Secret**: Confluent Cloud API 시크릿
    * **Consumer Group**: OneSignal용 고유한 그룹 ID(예: `onesignal-events`)
    * **Schema Registry URL** (선택 사항): Confluent Schema Registry를 사용하는 경우
  </Step>

  <Step title="이벤트 토픽 구성">
    이벤트 데이터를 포함하는 Confluent Cloud 토픽을 지정하세요:

    * **Topic Names**: 소비할 토픽의 쉼표로 구분된 목록(예: `user-events,purchase-events`)
    * **Event Format**: JSON, Avro 또는 Protobuf 메시지 형식
    * **Schema Registry**: 구조화된 스키마를 사용하는 경우 활성화

    이벤트 메시지에는 다음이 포함되어야 합니다:

    * 이벤트 이름/유형 (String)
    * 사용자 식별자 (String)
    * 이벤트 타임스탬프 (Long/ISO 형식)
    * 추가 이벤트 속성 (중첩된 JSON)
  </Step>

  <Step title="연결 테스트">
    **Test Connection**을 클릭하여 OneSignal이 Confluent Cloud 클러스터에 연결하고 이벤트 메시지를 소비할 수 있는지 확인하세요.
  </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  |

***

## 고급 구성

### 스키마 레지스트리 통합

구조화된 이벤트 데이터를 위해 Confluent Schema Registry를 활용하세요:

```json theme={null}
{
  "schema": "user_event_schema_v1",
  "data": {
    "event_name": "purchase",
    "user_id": "user_12345",
    "event_timestamp": 1640995200000,
    "properties": {
      "product_id": "prod_abc123",
      "amount": 29.99,
      "currency": "USD"
    }
  }
}
```

### Consumer Group 관리

OneSignal은 메시지 오프셋을 추적하기 위해 전용 컨슈머 그룹을 만듭니다:

* **자동 커밋**: 성공적인 처리 후 오프셋이 자동으로 커밋됨
* **오류 처리**: 재시도 메커니즘으로 실패한 메시지가 기록됨
* **확장**: OneSignal 컨슈머 인스턴스 전체에서 파티션 균형 조정

### 실시간 처리

Confluent Cloud는 거의 실시간 이벤트 활성화를 가능하게 합니다:

* **낮은 지연 시간**: 게시된 후 몇 초 내에 이벤트가 처리됨
* **높은 처리량**: 초당 수천 개의 이벤트 처리
* **장애 허용**: 내장된 복제 및 자동 장애 조치

<Warning>
  Confluent Cloud 클러스터에 다른 컨슈머와 함께 OneSignal의 소비 속도를 처리할 수 있는 충분한 처리량 용량이 있는지 확인하세요.
</Warning>

***

## FAQ

### OneSignal이 Confluent Cloud에서 이벤트를 얼마나 자주 소비하나요?

OneSignal은 토픽에 도착하는 즉시 이벤트를 실시간으로 소비하며 최소 지연 시간(일반적으로 5초 미만)으로 처리합니다.

### 여러 토픽에서 동시에 소비할 수 있나요?

예, OneSignal은 여러 토픽에서 병렬로 소비할 수 있습니다. 구성에서 토픽 이름을 쉼표로 구분된 목록으로 지정하세요.

### OneSignal이 Confluent Cloud에 연결할 수 없으면 어떻게 되나요?

OneSignal은 지수 백오프로 연결을 재시도합니다. 연결이 복원되면 이벤트 소비가 자동으로 재개됩니다.