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

# Pub/Sub

> Google Pub/Sub에서 OneSignal로 사용자 지정 이벤트를 동기화하여 실시간 사용자 행동을 기반으로 자동화된 저니와 개인화된 메시징 캠페인을 트리거하세요.

export const PLATFORM_0 = "Pub/Sub"

export const DATA_TYPE_0 = "message fields"

export const COLUMN_HEADER_0 = "Pub/Sub Message Field"

export const PROPERTIES_DESCRIPTION_0 = "이벤트 세부 정보가 포함된 JSON 객체"

## 개요

OneSignal + Google Pub/Sub 통합은 Pub/Sub 토픽에서 OneSignal로 사용자 지정 이벤트를 실시간으로 동기화하여 사용자 행동을 기반으로 자동화된 메시징 캠페인과 저니를 트리거할 수 있게 합니다.

Pub/Sub은 애플리케이션이 독립적인 구성 요소 간에 메시지를 보내고 받을 수 있도록 하는 Google의 확장 가능한 메시징 서비스입니다. OneSignal은 Pub/Sub 토픽의 구독자로 작동하여 Pub/Sub의 이벤트 메시지를 동기화하여 개인화된 사용자 경험을 트리거할 수 있습니다.

***

## 요구 사항

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

### Google Pub/Sub

* Pub/Sub이 활성화된 **Google Cloud Project**
* 이벤트 메시지가 포함된 **Pub/Sub 토픽**
* 서비스 계정 액세스를 부여하기 위한 **IAM 권한**
* 토픽의 **JSON 형식 메시지**

***

## 설정

<Steps>
  <Step title="Pub/Sub 연결 생성">
    OneSignal에서 **Data > Integrations**으로 이동하여 **Add Integration**을 클릭합니다.

    1. 목록에서 **Google Pub/Sub**을 선택합니다
    2. Pub/Sub 토픽이 있는 위치의 **GCP Project ID**를 입력합니다
    3. 인증 방법을 선택합니다:
       * **자동 생성된 서비스 계정** (권장): OneSignal이 서비스 계정을 생성하고 관리합니다
       * **기존 서비스 계정**: 자체 서비스 계정 키 JSON 파일을 제공합니다
    4. **연결**을 클릭합니다
  </Step>

  <Step title="서비스 계정에 권한 부여">
    OneSignal이 새 서비스 계정을 생성하고 서비스 계정 이메일 주소를 제공합니다.

    GCP 프로젝트에서 이 서비스 계정에 **`roles/pubsub.editor`** 역할을 부여합니다:

    ```bash theme={null}
    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:SERVICE_ACCOUNT_EMAIL \
      --role roles/pubsub.editor
    ```

    OneSignal은 이 역할을 사용하여:

    * 이벤트 토픽에 대한 구독 생성
    * 토픽에서 이벤트 메시지 소비
    * 실패한 처리를 위한 오류 토픽(Dead Letter Queue) 생성
  </Step>

  <Step title="연결 테스트">
    필요한 권한을 부여한 후 OneSignal에서 **저장**을 클릭하여 연결을 확인합니다.

    OneSignal은 Pub/Sub 토픽에 액세스할 수 있고 이벤트 메시지를 처리할 준비가 되었는지 확인합니다.
  </Step>
</Steps>

***

## 이벤트 데이터 스키마

사용자 지정 이벤트에 Pub/Sub 토픽을 사용하려면 먼저 이벤트 메시지의 스키마를 정의해야 합니다.

<Steps>
  <Step title="이벤트 스키마 정의로 이동">
    OneSignal에서 **데이터 > 통합**으로 이동하여 Pub/Sub 연결을 선택합니다.

    OneSignal은 프로젝트에서 토픽 목록을 자동으로 가져옵니다. **토픽 새로 고침**을 클릭하여 수동으로 목록을 새로 고칩니다.
  </Step>

  <Step title="이벤트 메시지 스키마 정의">
    1. 이벤트 데이터가 포함된 토픽 이름을 클릭합니다
    2. 메시지 형식으로 **JSON**을 선택합니다 (유일하게 지원되는 형식)
    3. **샘플 메시지 가져오기**를 클릭하고 샘플 이벤트 메시지를 제공합니다
    4. 감지된 스키마를 검토하여 적절한 필드 매핑을 확인합니다
    5. **데이터 세트 저장**을 클릭합니다
  </Step>
</Steps>

### 이벤트 메시지 형식

OneSignal 사용자 지정 이벤트의 경우 Pub/Sub 메시지는 다음 JSON 구조를 따라야 합니다:

```json theme={null}
{
  "event_name": "purchase_completed",
  "user_id": "user_12345",
  "timestamp": "2023-12-01T10:30:00Z",
  "properties": {
    "product_id": "prod_abc123",
    "price": 29.99,
    "category": "electronics",
    "payment_method": "credit_card"
  },
  "session_id": "session_789"
}
```

### 이벤트 데이터 매핑

{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  |

<Warning>
  샘플 메시지에 고객 PII 또는 민감한 데이터를 포함하지 마세요. OneSignal은 데이터 세트 정의의 일부로 메시지 샘플을 저장합니다.
</Warning>

***

## 실시간 이벤트 처리

일괄 처리 통합과 달리 Pub/Sub은 거의 실시간 이벤트 처리를 지원합니다:

* **짧은 대기 시간**: 이벤트는 토픽에 게시된 후 몇 초 이내에 처리됩니다
* **자동 구독**: OneSignal은 각 토픽에 대한 전용 구독을 생성합니다
* **오류 처리**: 실패한 이벤트는 조사를 위해 Dead Letter Queue 토픽으로 전송됩니다
* **확장 가능한 처리**: 대용량 이벤트 스트림을 자동으로 처리합니다

***

## 고급 구성

### Dead Letter Queue

OneSignal은 처리에 실패한 이벤트에 대한 오류 토픽을 자동으로 생성합니다:

* **자동 생성**: 오류 토픽은 구독당 생성됩니다
* **실패한 이벤트 저장**: 처리할 수 없는 이벤트는 디버깅을 위해 저장됩니다
* **수동 검토**: Google Cloud Console을 통해 실패한 이벤트에 액세스하여 문제를 해결합니다

### 메시지 승인

OneSignal은 Pub/Sub 메시지 승인을 자동으로 처리합니다:

* **성공적인 처리**: 메시지는 이벤트 생성 성공 후 승인됩니다
* **실패한 처리**: 메시지는 부정적으로 승인되고 Dead Letter Queue로 전송됩니다
* **재시도 로직**: 일시적인 장애에 대한 기본 재시도 처리

***

## 제한 사항

* JSON 메시지 형식만 지원됩니다
* 메시지 샘플은 데이터 세트 정의의 일부로 저장됩니다 (PII 방지)
* 프로젝트 수준에서 `roles/pubsub.editor` 권한이 필요합니다
* 최대 메시지 크기는 Google Pub/Sub 제한(10MB)을 따릅니다

***

## FAQ

### 이벤트는 얼마나 빨리 처리되나요?

이벤트는 일반적으로 Pub/Sub 토픽에 게시된 후 몇 초 이내에 처리되어 거의 실시간 저니 트리거링이 가능합니다.

### OneSignal이 이벤트를 처리할 수 없으면 어떻게 되나요?

실패한 이벤트는 OneSignal이 생성하는 Dead Letter Queue 토픽으로 자동으로 전송됩니다. Google Cloud Console에서 이러한 이벤트를 검토하여 디버깅할 수 있습니다.

### 다양한 이벤트 유형에 여러 토픽을 사용할 수 있나요?

예, 동일한 GCP 프로젝트 내에서 여러 토픽에 대한 스키마를 정의할 수 있습니다. 각 토픽은 자체 스키마 정의를 가진 다른 이벤트 유형을 포함할 수 있습니다.