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

# Google BigQuery

> 메시징 이벤트 데이터를 BigQuery로 내보내고 BigQuery에서 사용자 지정 이벤트를 가져와 개인화된 캠페인을 트리거하세요.

export const PLATFORM_0 = "BigQuery"

export const DATA_TYPE_0 = "event table columns"

export const COLUMN_HEADER_0 = "BigQuery Column"

export const PROPERTIES_DESCRIPTION_0 = "Additional columns as JSON"

## 개요

OneSignal + BigQuery 통합은 두 가지 강력한 데이터 파이프라인을 지원합니다:

* **내보내기**: OneSignal의 메시징 이벤트 데이터(푸시, 이메일, SMS, 인앱)를 BigQuery로 자동으로 전송하여 분석 및 보고합니다.
* **가져오기**: BigQuery 데이터 세트의 사용자 지정 사용자 이벤트를 OneSignal로 동기화하여 자동화된 Journeys 및 개인화된 메시징을 트리거합니다.

함께 사용하면 이러한 통합을 통해 사용자 참여 데이터를 완전히 제어하여 고급 분석 및 실시간 행동 기반 메시징을 지원합니다.

***

## OneSignal 이벤트를 BigQuery로 내보내기

메시징 성능 및 참여 이벤트(예: 전송, 열기, 클릭)를 BigQuery로 전송하여:

* 사용자 지정 대시보드 및 보고서 구축
* 채널 전반에 걸친 전달 및 참여 추세 추적
* 분석을 위해 OneSignal 데이터를 다른 비즈니스 데이터와 결합

**요구 사항**

* 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 Cloud Platform 프로젝트
- GCP 프로젝트에서 활성화된 BigQuery
- BigQuery 쓰기 권한이 있는 서비스 계정

**설정 단계**

### 1. 서비스 계정 만들기

<Steps>
  <Step title="Google Cloud Platform 계정에 로그인">
    로그인한 후 적절한 프로젝트가 선택되었는지 확인합니다.

    <Frame>
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=038779c4d976ba56a17a32f2e6646573" width="2388" height="558" data-path="images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png" />
    </Frame>
  </Step>

  <Step title="서비스 계정 만들기">
    [서비스 계정 만들기 페이지](https://console.cloud.google.com/iam-admin/serviceaccounts/create)를 방문하고 **서비스 계정 만들기**를 클릭합니다.

    <Frame>
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=038779c4d976ba56a17a32f2e6646573" width="2388" height="558" data-path="images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png" />
    </Frame>
  </Step>

  <Step title="필드 작성">
    원하는 이름과 서비스 계정 ID를 지정합니다.

    <Frame>
      <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/6437e9849e23f18ec6f90e03c3821817566e7f150125f440a58fbe5fd2b42e0b-BQ1-3.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=37236688a79f1c16c0d6fdad15b03245" width="1344" height="870" data-path="images/docs/6437e9849e23f18ec6f90e03c3821817566e7f150125f440a58fbe5fd2b42e0b-BQ1-3.png" />
    </Frame>
  </Step>

  <Step title="'BigQuery User' 역할 할당">
    서비스 계정에 "BigQuery User" 역할을 부여합니다.

    <Frame>
      <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b1bff32d7f010b488b60347e01ecb1fbde182602f19f16d3d89914d1de1c0635-BQ1-4.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=1df75028d3632a3ed413c10c1de9b94a" width="549" height="395" data-path="images/docs/b1bff32d7f010b488b60347e01ecb1fbde182602f19f16d3d89914d1de1c0635-BQ1-4.png" />
    </Frame>
  </Step>

  <Step title="이 계정에 대한 JSON 키 만들기">
    새 서비스 계정 > **키** > **키 추가** > **새 키 만들기**로 이동하여 JSON을 선택합니다. 파일을 저장합니다.
  </Step>
</Steps>

<Info>
  이 JSON 키 파일의 전체 내용을 OneSignal에 붙여넣어 통합을 활성화합니다.
</Info>

### 2. OneSignal에서 통합 활성화

<Steps>
  <Step title="OneSignal > 데이터 > 통합 > BigQuery로 이동" />

  <Step title="서비스 계정 JSON 키 붙여넣기" />

  <Step title="설정 구성">
    * **동기화 빈도**: 15분마다 동기화 가능
    * **데이터 세트/테이블 이름**: 소문자, 숫자 및 밑줄만 포함해야 하며 숫자로 시작할 수 없습니다.
    * **이벤트 유형**: 특정 메시지 이벤트 선택(예: 전송됨, 열림, 클릭됨)
      * **참고:** 여러 이벤트 유형을 선택하거나 나중에 선택한 이벤트를 업데이트할 수 있습니다.
  </Step>

  <Step title="저장을 클릭하고 확인 대기" />
</Steps>

<Note>
  초기 데이터 동기화는 BigQuery에 나타나는 데 15-30분이 걸릴 수 있습니다.

  대기하는 동안 푸시, 이메일, 인앱 또는 SMS를 통해 메시지를 보내 선택한 이벤트를 트리거하세요.
</Note>

### 3. BigQuery에서 데이터 보기

BigQuery 콘솔을 열고 데이터 세트(예: `onesignal_events_<app-id>`)를 찾아 동기화된 메시지 이벤트를 탐색합니다.

<Frame caption="BigQuery dataset containing exported message events">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/c40ec987eadef5dd1c16cb47fb71c2c666b30ea8667624584ecbc481c12ef026-BQ5.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=08cf57a8bd91f9447909ad619077935f" width="1552" height="1052" data-path="images/docs/c40ec987eadef5dd1c16cb47fb71c2c666b30ea8667624584ecbc481c12ef026-BQ5.png" />
</Frame>

## 메시지 이벤트 및 속성

### 메시지 이벤트 종류

**속성:** `event_kind`
**유형:** `String`

메시지 및 이벤트의 종류(예: `message.push.received`, `message.push.sent`).

|   메시지 이벤트 (OneSignal)  |           `event_kind`           | 설명                                                                |
| :--------------------: | :------------------------------: | ----------------------------------------------------------------- |
|        Push Sent       |        `message.push.sent`       | 푸시 알림이 성공적으로 전송되었습니다.                                             |
|      Push Received     |      `message.push.received`     | 전달된 푸시([전달 확인](/docs/ko/confirmed-delivery) 참조).                  |
|      Push Clicked      |      `message.push.clicked`      | 사용자가 푸시를 클릭했습니다.                                                  |
|       Push Failed      |       `message.push.failed`      | 전달 실패. 메시지 보고서를 참조하세요.                                            |
|    Push Unsubscribed   |    `message.push.unsubscribed`   | 사용자가 푸시 구독을 취소했습니다.                                               |
|    In-App Impression   |     `message.iam.impression`     | 인앱 메시지가 표시되었습니다.                                                  |
|     In-App Clicked     |       `message.iam.clicked`      | 인앱 메시지를 클릭했습니다.                                                   |
|   In-App Page Viewed   |   `message.iam.page_displayed`   | 인앱 페이지가 표시되었습니다.                                                  |
|       Email Sent       |       `message.email.sent`       | 이메일이 전달되었습니다.                                                     |
|     Email Received     |     `message.email.received`     | 수신자의 메일 서버가 이메일을 수락했습니다.                                          |
|      Email Opened      |      `message.email.opened`      | 이메일이 열렸습니다. [이메일 보고서](/docs/ko/email-message-reports)를 참조하세요.     |
|   Email Link Clicked   |      `message.email.clicked`     | 이메일의 링크를 클릭했습니다.                                                  |
|   Email Unsubscribed   |   `message.email.unsubscribed`   | 수신자가 구독을 취소했습니다.                                                  |
| Email Reported As Spam | `message.email.reported_as_spam` | 스팸으로 표시되었습니다. [이메일 전달 가능성](/docs/ko/email-deliverability)을 참조하세요. |
|      Email Bounced     |      `message.email.bounced`     | 영구적인 전달 실패로 인한 반송.                                                |
|      Email Failed      |      `message.email.failed`      | 전달이 실패했습니다.                                                       |
|    Email Suppressed    |    `message.email.suppressed`    | 억제 목록으로 인해 억제되었습니다.                                               |
|        SMS Sent        |        `message.sms.sent`        | SMS가 전송되었습니다.                                                     |
|      SMS Delivered     |      `message.sms.delivered`     | SMS가 성공적으로 전달되었습니다.                                               |
|       SMS Failed       |       `message.sms.failed`       | SMS 전달이 실패했습니다.                                                   |
|     SMS Undelivered    |     `message.sms.undelivered`    | SMS가 거부되었거나 도달할 수 없습니다.                                           |

### 이벤트 데이터 스키마

사용자가 생성한 각 메시지 이벤트에 대해 다음 메타데이터가 레코드에 첨부됩니다.

|                       열 이름                      |     유형    | 설명                                      |
| :---------------------------------------------: | :-------: | --------------------------------------- |
|                    `event_id`                   |    UUID   | 이벤트의 고유 식별자                             |
|                `event_timestamp`                | Timestamp | 이벤트 발생 시간                               |
|                   `event_kind`                  |   String  | [이벤트 종류](#메시지-이벤트-종류)                   |
|            `subscription_device_type`           |   String  | 장치 유형(예: iOS, Android, Web, Email, SMS) |
|                    `language`                   |   String  | 구독 언어 코드                                |
|                    `version`                    |   String  | 통합 버전                                   |
|                   `device_os`                   |   String  | 장치 운영 체제 버전                             |
|                  `device_type`                  |   Number  | 숫자 장치 유형                                |
|                     `token`                     |   String  | 푸시 토큰, 전화번호 또는 이메일                      |
|                `subscription_id`                |    UUID   | 구독 ID                                   |
|                   `subscribed`                  |  Boolean  | 구독 상태                                   |
|                  `onesignal_id`                 |    UUID   | OneSignal 사용자 ID                        |
|                  `last_active`                  |   String  | 마지막 활성 타임스탬프                            |
|                      `sdk`                      |   String  | OneSignal SDK 버전                        |
|                  `external_id`                  |   String  | 통합 사용자 ID와 일치해야 하는 외부 사용자 ID            |
|                     `app_id`                    |    UUID   | OneSignal의 앱 ID                         |
|                  `template_id`                  |    UUID   | 템플릿 ID(해당하는 경우)                         |
|                   `message_id`                  |    UUID   | 메시지 배치/요청 ID                            |
|                  `message_name`                 |   String  | 메시지 이름                                  |
|                 `message_title`                 |   String  | 메시지 제목(영어만)                             |
|                `message_contents`               |   String  | 잘린 메시지 본문(영어만)                          |
|                 `failure_reason`                |   String  | 실패 이유(푸시 실패 및 이메일 실패 이벤트용)              |
| `_created`, `_id`, `_index`, `_fivetran_synced` |  *내부 사용*  | Fivetran 동기화 메타데이터                      |

### 참고 사항

* 저장/활성화 후 동기화는 완료하는 데 추가로 15-30분이 소요될 수 있습니다.
* 비활성화하면 비활성화 후 최종 동기화가 한 번 더 발생할 수 있습니다.
* 효율적인 데이터 동기화를 보장하기 위해 시스템은 스테이징 데이터 세트를 자동으로 생성하고 관리합니다. 이러한 데이터 세트는 `fivetran_{두 개의 무작위 단어}_staging`과 같은 패턴으로 이름이 지정되며, 기본 스키마에 통합되기 전에 처리 중에 데이터를 임시로 저장합니다. 이러한 스테이징 데이터 세트는 간소화된 워크플로를 유지하는 데 필수적이며 자동으로 다시 생성되므로 삭제하면 안 됩니다.

***

## BigQuery에서 이벤트 가져오기

BigQuery의 행동 이벤트 데이터를 OneSignal로 전송하여:

* 사용자 활동을 기반으로 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)

- BigQuery 및 이벤트 데이터 테이블이 있는 GCP 프로젝트
- 읽기 권한이 있는 서비스 계정
- BigQuery 데이터 세트에 행동 데이터가 포함된 이벤트 데이터 테이블

**설정 단계**

<Steps>
  <Step title="BigQuery 서비스 계정 만들기">
    OneSignal은 연결을 만들 때 자동으로 서비스 계정을 생성합니다. 또는 자체 서비스 계정 키 JSON 파일을 제공할 수 있습니다.

    자체 서비스 계정을 만드는 경우 아래에 나열된 필수 권한이 있는지 확인하세요.
  </Step>

  <Step title="필수 권한 부여">
    OneSignal 서비스 계정에는 다음 BigQuery IAM 역할이 필요합니다:

    * **`bigquery.dataViewer`** - 이벤트 데이터가 포함된 데이터 세트 및 테이블에 대한 읽기 액세스
    * **`bigquery.jobUser`** - 데이터 쿼리를 위한 작업 생성 권한
    * **`bigquery.metadataViewer`** - 프로젝트 수준 메타데이터 액세스(권장)

    Google Cloud Console 또는 CLI를 사용하여 권한을 부여합니다:

    ```bash theme={null}
    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
      --role roles/bigquery.dataViewer

    gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
      --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
      --role roles/bigquery.jobUser
    ```
  </Step>

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

    <Frame caption="BigQuery 통합 추가">
      <img src="https://mintcdn.com/onesignal/IHzVtEbivOs2EktQ/images/integrations/bigquery-add-integration.png?fit=max&auto=format&n=IHzVtEbivOs2EktQ&q=85&s=6877dc14cfe8f9c1677404353927e4f8" width="1944" height="1764" data-path="images/integrations/bigquery-add-integration.png" />
    </Frame>

    * **동기화 엔진**: 대규모 데이터 세트 또는 복잡한 이벤트 데이터 쿼리에는 고급 동기화가 권장됩니다. 기본 동기화로 시작한 다음 필요한 경우 나중에 고급 동기화로 전환할 수 있습니다.
    * **Google Cloud 프로젝트 ID**: BigQuery 데이터 세트가 포함된 GCP 프로젝트
    * **데이터 세트 지역**: BigQuery 데이터 세트가 저장된 위치
    * **서비스 계정 키** (선택 사항): 자체 서비스 계정을 사용하는 경우 JSON 키 파일
  </Step>

  <Step title="이벤트 데이터 소스 구성">
    이벤트 데이터가 포함된 BigQuery 데이터 세트 및 테이블을 지정합니다:

    * **데이터 세트**: BigQuery 데이터 세트 이름(예: `analytics_events`)
    * **테이블/뷰**: 이벤트 레코드가 포함된 테이블 또는 뷰
    * **이벤트 쿼리**: 이벤트 데이터를 필터링하거나 변환하기 위한 선택적 SQL 쿼리

    이벤트 테이블에는 다음에 대한 열이 포함되어야 합니다:

    * 이벤트 이름/유형
    * 사용자 식별자
    * 이벤트 타임스탬프
    * 추가 이벤트 속성
  </Step>

  <Step title="연결 테스트">
    **연결 테스트**를 클릭하여 OneSignal이 BigQuery 프로젝트에 액세스하고 이벤트 데이터를 읽을 수 있는지 확인합니다.
  </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  |

### 고급 구성

#### 사용자 지정 SQL 쿼리

OneSignal로 동기화하기 전에 사용자 지정 SQL을 사용하여 이벤트 데이터를 필터링하거나 변환합니다:

```sql theme={null}
SELECT
  event_name,
  user_id,
  event_timestamp,
  STRUCT(
    product_id,
    purchase_amount,
    category
  ) as payload
FROM `project.dataset.events`
WHERE event_timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
```

#### 교차 프로젝트 액세스

이벤트 데이터가 여러 BigQuery 프로젝트에 걸쳐 있는 경우 참조된 테이블 또는 뷰가 포함된 각 프로젝트에 OneSignal 서비스 계정 액세스를 부여합니다.

<Warning>
  최적의 성능을 위해 BigQuery 연결 지역이 특정 테이블 지역과 일치해야 합니다.
</Warning>

***

## FAQ

### 동기화가 실패하는 이유는 무엇인가요?

동기화가 실패하는 몇 가지 일반적인 이유가 있습니다:

* 서비스 계정에 필요한 권한이 없습니다
* 소스 데이터 세트가 기본 동기화에 비해 너무 크며 고급 동기화를 사용해야 합니다

위의 설정 단계를 검토하고 올바르게 따랐는지 확인하세요. 여전히 문제가 있는 경우 `support@onesignal.com`에 문의하세요.

### 동일한 콘텐츠에 대해 여러 메시지 ID가 표시되는 이유는 무엇인가요?

일반적으로 메시지 템플릿이 여러 전송 또는 트리거된 플로우에서 재사용될 때 발생합니다.

### OneSignal은 얼마나 자주 데이터를 동기화하나요?

내보내기 및 가져오기 통합 모두 15분마다 동기화할 수 있습니다.

### BigQuery 뷰를 사용할 수 있나요?

예. 서비스 계정이 뷰에서 참조된 모든 테이블에 액세스할 수 있는지 확인하기만 하면 됩니다.

***

## 관련 리소스

* [GCP에서 서비스 계정 키 만들기](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating)
* [OneSignal Journeys 문서](./journeys-overview)
* [OneSignal 데이터 내보내기 문서](./exporting-data)

***