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

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

export const PLATFORM_0 = "Google Sheets"

export const DATA_TYPE_0 = "columns"

export const COLUMN_HEADER_0 = "Sheets Column Examples"

export const PROPERTIES_DESCRIPTION_0 = "JSON으로 결합된 여러 열"

## 개요

OneSignal + Google Sheets 통합은 Google Sheets에서 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 Sheets

* 이벤트 데이터가 포함된 시트에 대한 액세스 권한이 있는 **Google 계정**
* 이벤트 데이터에 대한 적절한 열 구조가 있는 **이벤트 스프레드시트**
* OneSignal이 데이터에 액세스할 수 있는 **시트 공유 권한**
* 이벤트 추적 시트의 **일관된 데이터 형식**

***

## 설정

<Steps>
  <Step title="이벤트 데이터 시트 준비">
    이벤트 데이터에 필요한 열로 Google Sheet을 구성합니다:

    **필수 열:**

    * `event_name` 또는 `event_type`: 이벤트 이름 (String)
    * `user_id` 또는 `email`: 사용자 식별자 (String)
    * `timestamp` 또는 `created_at`: 이벤트 타임스탬프 (Date/DateTime)
    * `properties`: JSON 또는 별도 열로 된 이벤트 속성 (선택 사항)

    **예제 시트 구조:**

    ```
    | event_name | user_id | timestamp           | product_id | amount |
    |------------|---------|---------------------|------------|--------|
    | purchase   | user123 | 2024-01-15 10:30:00 | prod_abc   | 29.99  |
    | signup     | user456 | 2024-01-15 11:45:00 |            |        |
    ```
  </Step>

  <Step title="시트 권한 구성">
    OneSignal의 서비스 계정과 Google Sheet을 공유합니다:

    1. Google Sheet을 엽니다
    2. 오른쪽 상단의 **공유** 버튼을 클릭합니다
    3. OneSignal의 서비스 계정 이메일을 추가합니다 (설정 중 제공됨)
    4. 권한을 **뷰어**(읽기 전용 액세스)로 설정합니다
    5. **전송**을 클릭하여 액세스 권한을 부여합니다

    <Info>
      OneSignal은 통합 설정 프로세스 중에 특정 서비스 계정 이메일을 제공합니다.
    </Info>
  </Step>

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

    **Google Sheets**를 선택하고 다음을 제공합니다:

    * **Sheet URL**: Google Sheet의 전체 URL
    * **Sheet Name**: 이벤트 데이터가 포함된 특정 탭/시트 이름
    * **Header Row**: 열 헤더가 포함된 행 번호 (일반적으로 1)
    * **Data Range**: 이벤트 데이터가 포함된 셀 범위 (예: `A2:F1000`)
  </Step>

  <Step title="열 매핑 구성">
    Google Sheets 열을 OneSignal 이벤트 필드에 매핑합니다:

    * **Event Name Column**: 이벤트 이름이 포함된 열을 선택합니다
    * **User ID Column**: 사용자 식별자가 있는 열을 선택합니다
    * **Timestamp Column**: 이벤트 타임스탬프가 있는 열을 선택합니다
    * **Properties Columns**: 이벤트 속성으로 포함할 추가 열을 선택합니다

    <Info>
      여러 열을 이벤트 속성으로 매핑할 수 있습니다. OneSignal은 이를 단일 이벤트 페이로드로 결합합니다.
    </Info>
  </Step>

  <Step title="동기화 일정 설정">
    OneSignal이 새 이벤트 데이터를 확인해야 하는 빈도를 구성합니다:

    * **Sync Frequency**: 15분, 시간별 또는 일별 중에서 선택합니다
    * **Incremental Sync**: 마지막 업데이트 이후 새 행만 동기화하려면 활성화합니다
    * **Timestamp Filter**: 특정 시간 범위 내의 이벤트만 동기화합니다

    <Warning>
      Google Sheets에는 API 속도 제한이 있습니다. 대규모 데이터 세트가 있는 시트의 경우 더 빈번한 동기화가 제한될 수 있습니다.
    </Warning>
  </Step>

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

***

## 고급 구성

### 증분 동기화 설정

새 이벤트만 처리하도록 증분 동기화를 구성합니다:

1. **Timestamp Column**: 시트에 일관된 타임스탬프 열이 있는지 확인합니다
2. **Sort Order**: 이벤트를 타임스탬프별로 정렬합니다 (최신 항목이 마지막)
3. **Append-Only**: 시트 하단에 새 이벤트를 추가합니다
4. **Avoid Edits**: 동기화된 후 과거 이벤트 행을 수정하지 마세요

### 데이터 유효성 검사

Google Sheet에서 데이터 유효성 검사를 구현합니다:

```
데이터 > 데이터 유효성 검사
- Event Name: 범위 목록 (사전 정의된 이벤트 유형)
- User ID: 형식을 확인하는 사용자 지정 수식
- Timestamp: 날짜/시간 형식 유효성 검사
- Amount: 숫자 속성에 대한 숫자 유효성 검사
```

### 공동 작업 워크플로

팀 협업을 위한 모범 사례:

* **Named Ranges**: 이벤트 데이터 섹션에 명명된 범위를 사용합니다
* **Protected Ranges**: 실수로 변경되지 않도록 헤더 행을 보호합니다
* **Comments**: 이벤트 정의를 설명하는 주석을 추가합니다
* **Version History**: 변경 사항을 추적하기 위해 Google Sheets의 버전 기록을 사용합니다
* **Access Controls**: 데이터 입력 팀 구성원으로 편집 액세스를 제한합니다

### 성능 최적화

대규모 데이터 세트에 대해 최적화합니다:

* **Sheet Limits**: 최상의 성능을 위해 개별 시트를 10,000행 미만으로 유지합니다
* **Multiple Sheets**: 다양한 이벤트 유형에 별도의 시트를 사용합니다
* **Data Archival**: 매월 별도의 시트에 오래된 데이터를 보관합니다
* **Formulas**: 이벤트 데이터 범위에서 복잡한 수식을 최소화합니다

<Warning>
  Google Sheets는 총 50,000개 미만의 셀에서 가장 잘 작동합니다. 대용량 이벤트 추적의 경우 대신 데이터베이스 소스를 사용하는 것을 고려하세요.
</Warning>

***

## FAQ

### OneSignal은 Google Sheets에서 얼마나 자주 이벤트를 동기화하나요?

OneSignal은 15분마다 동기화할 수 있지만 Google의 API 제한을 준수하기 위해 대부분의 사용 사례에서 시간별 또는 일별 동기화를 권장합니다.

### 여러 팀 구성원이 동일한 시트에 이벤트를 추가할 수 있나요?

예, Google Sheets는 실시간 협업을 지원합니다. 그러나 팀 구성원이 필요한 데이터 형식과 열 구조를 이해하는지 확인하세요.

### 누군가 과거 이벤트 데이터를 편집하면 어떻게 되나요?

OneSignal은 타임스탬프와 행 위치를 기반으로 동기화합니다. 과거 데이터를 편집하면 중복 이벤트 또는 데이터 불일치가 발생할 수 있습니다. 추가 전용 워크플로를 권장합니다.