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

# 사용자 지정 이벤트

> 사용자 지정 이벤트로 사용자 행동을 추적하고 Journeys 트리거, Wait Until 단계로 흐름 제어, 실시간 메시지 개인화에 활용하세요.

## 사용자 지정 이벤트란?

사용자 지정 이벤트는 OneSignal에 전송하는 명명된 사용자 행동(또는 비행동)입니다. 앱, 웹사이트 또는 외부 시스템에서 이벤트를 전송하여 자동화를 트리거하고, Journey 흐름을 제어하며, 실시간으로 사용자 경험을 개인화할 수 있습니다.

**예시:**

* 온보딩 완료
* 구매 완료
* 장바구니 이탈
* 구독 취소
* 새로운 게임 레벨 도달

**OneSignal이 사용자 지정 이벤트를 수신하면 다음을 수행할 수 있습니다:**

* Journey 시작
* Wait Until 단계로 Journey 진행
* Journey에서 사용자 퇴장
* 이벤트 속성을 사용한 메시지 개인화
* 행동 기반 사용자 세분화 (Early Access)

### 사용자 지정 이벤트는 언제 사용해야 하나요?

다음과 같은 경우 사용자 지정 이벤트를 사용하세요:

* 메시징이 실시간 사용자 행동에 반응해야 할 때
* 데이터가 발생한 사건을 나타낼 때 (영구적인 상태가 아닌 경우)
* 개인화 또는 Journey 로직에 이벤트 속성이 필요할 때

다음과 같은 경우에는 사용자 지정 이벤트를 사용하지 마세요:

* 장기적인 사용자 속성을 저장하려는 경우 (대신 태그를 사용하세요)

<Warning>
  사용자 지정 이벤트는 특정 시점에 발생한 사건을 나타냅니다. 태그와 달리 사용자 프로필을 영구적으로 업데이트하지 않으며, 행동을 기록합니다.

  자세한 비교는 아래의 [태그 vs 사용자 지정 이벤트](#tags-vs-custom-events)를 참조하세요.
</Warning>

### 사용자 지정 이벤트 구조

사용자 지정 이벤트에는 다음 필드가 포함됩니다:

<ParamField body="name" type="string" required>
  이벤트 이름. 최대 `128`자.
</ParamField>

<ParamField body="properties" type="object">
  이벤트를 설명하는 선택적 매개변수(예: 플랜 이름, 제품 ID 또는 가격). 개인화 및 Journey 흐름 제어에 사용할 수 있습니다.
</ParamField>

<ParamField body="external_id" type="string">
  사용자의 External ID. [Create Custom Events API](/reference/create-custom-events)를 사용할 때 사용자 식별자가 필요합니다. `external_id` 또는 `onesignal_id` 중 하나를 제공해야 합니다.
</ParamField>

<ParamField body="timestamp" type="string">
  이벤트가 발생했거나 발생할 시간으로, ISO 8601 문자열 형식입니다. [Create Custom Events API](/reference/create-custom-events)를 참조하세요.
</ParamField>

<ParamField body="idempotency_key" type="string">
  중복 이벤트 처리를 방지하기 위한 고유 UUID입니다. [Create Custom Events API](/reference/create-custom-events)를 참조하세요.
</ParamField>

<Warning>
  이벤트 크기 제한:

  * 최대 이벤트 페이로드: 2024 바이트
  * 최대 요청 크기 (여러 이벤트): 1 MB
</Warning>

***

## OneSignal로 사용자 지정 이벤트 전송

<Info>
  모든 이벤트는 소스에 관계없이 청구 목적상 동일하게 처리됩니다.
</Info>

### API 및 SDK

<Columns cols={2}>
  <Card title="Create Custom Events API" icon="server" href="/reference/create-custom-events">
    백엔드에서 이벤트를 전송합니다.
  </Card>

  <Card title="Mobile/Web SDKs" icon="mobile" href="./mobile-sdk-reference#custom-events">
    클라이언트 측에서 이벤트를 추적합니다.
  </Card>
</Columns>

사용자 지정 이벤트 페이로드 예시:

```json JSON theme={null}
{
  "events": [
    {
      "name": "purchase",
      "properties": {
        "item": "T-shirt",
        "size": "small",
        "color": "blue",
        "price": 24.99
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:09:32.263Z",
      "idempotency_key": "123e4567-e89b-12d3-a456-426614174000"
    }
  ]
}
```

### 통합

OneSignal은 데이터 웨어하우스, 데이터베이스, 스트리밍 플랫폼 등 25개 이상의 외부 데이터 소스에 연결하여 커스텀 이벤트를 가져옵니다 — 커스텀 코드 없이도 사용 가능합니다.

<Columns cols={3}>
  <Card title="Twilio Segment" icon="share-nodes" href="./segment-onesignal-integration">
    Segment와 OneSignal 간에 이벤트와 오디언스를 라우팅합니다.
  </Card>

  <Card title="Amplitude" icon="chart-line" href="./amplitude">
    코호트를 동기화하고 Amplitude에서 커스텀 이벤트를 가져옵니다.
  </Card>

  <Card title="Mixpanel" icon="chart-mixed" href="./mixpanel">
    코호트를 동기화하고 Mixpanel에서 커스텀 이벤트를 가져옵니다.
  </Card>

  <Card title="Snowflake" icon="snowflake" href="./snowflake">
    Snowflake 웨어하우스에서 커스텀 이벤트를 가져옵니다.
  </Card>

  <Card title="Google BigQuery" icon="database" href="./bigquery">
    BigQuery 데이터셋에서 커스텀 이벤트를 가져옵니다.
  </Card>

  <Card title="Apache Kafka" icon="bolt" href="./kafka">
    Kafka 토픽에서 커스텀 이벤트를 스트리밍합니다.
  </Card>
</Columns>

<Card title="모든 커스텀 이벤트 소스 보기" icon="grid-2" href="./integrations#custom-event-sources">
  OneSignal로 커스텀 이벤트를 가져오는 데이터베이스, 웨어하우스, 스트리밍 플랫폼의 전체 목록을 확인하세요.
</Card>

<Tip>
  **개발자 리소스가 없으신가요?** [Google Sheets](./google-sheets) 스프레드시트에서 커스텀 이벤트를 직접 가져오세요 — 코드 없이 사용 가능합니다. 시트에 이벤트 데이터를 추가하면 OneSignal이 자동으로 가져옵니다. 초기 실험이나 엔지니어링 지원이 없는 팀에 적합합니다.
</Tip>

### 이벤트 수신 확인

이벤트를 전송한 후 **Data > Custom Events**에서 OneSignal에 도달하고 있는지 확인하세요.

#### Event List 탭

<Frame caption="OneSignal 대시보드 Data > Custom Events의 Event List 탭">
  <img src="https://mintcdn.com/onesignal/MWGmj5X1CnFliD-c/images/dashboard/event-list.png?fit=max&auto=format&n=MWGmj5X1CnFliD-c&q=85&s=2b9cae667bed4b54974326ffa0830907" width="3302" height="1888" data-path="images/dashboard/event-list.png" />
</Frame>

Event List 탭은 이벤트 이름별로 정리된 앱의 모든 사용자 지정 이벤트 개요를 제공합니다.

각 이벤트 유형에 대해 다음을 확인할 수 있습니다:

* 수집된 총 이벤트 수
* 가장 최근 이벤트 (전체 JSON 페이로드 및 속성 포함)
* 이벤트 소스 (SDK, API 또는 통합)
* 마지막 발생 타임스탬프

이벤트를 선택하면 세부 보기가 열리며, 보존 기간도 업데이트할 수 있습니다.

세부 보기에는 다음이 포함됩니다:

* **Source Breakdown**: 소스별 수집된 이벤트 수. 확장하면 최신 이벤트 스키마와 가장 최근 이벤트의 타임스탬프를 볼 수 있습니다.
* **Activities**: 소스와 타임스탬프를 포함한 가장 최근 10개의 이벤트. 항목을 확장하면 전체 JSON 페이로드를 확인할 수 있습니다.
* **Usage**: 이벤트가 현재 사용되는 위치 (Journeys 또는 세그먼트). 연결된 Journey 또는 세그먼트를 직접 클릭하여 설정을 수정할 수 있습니다.

#### Event Activity 탭

<Frame caption="OneSignal 대시보드 Data > Custom Events의 Event Activity 탭">
  <img src="https://mintcdn.com/onesignal/MWGmj5X1CnFliD-c/images/dashboard/event-activity.png?fit=max&auto=format&n=MWGmj5X1CnFliD-c&q=85&s=8e355c907b598f1ac5a446e3536b9eea" width="3302" height="1888" data-path="images/dashboard/event-activity.png" />
</Frame>

Event Activity 탭은 OneSignal 앱에 수집된 가장 최근 이벤트의 라이브 피드를 제공합니다.

다음과 같이 활용할 수 있습니다:

* 이벤트 이름, 소스 또는 External ID로 필터링
* 전체 JSON 페이로드 확인
* 통합 문제 디버깅

<Warning> 피드는 자동으로 새로고침되지 않습니다. 새 이벤트를 전송한 후 수동으로 새로고침하세요. </Warning>

***

## OneSignal에서 사용자 지정 이벤트 활용

이벤트가 OneSignal로 유입되기 시작하면 다음과 같은 방법으로 활용할 수 있습니다:

### Journey 진입 및 퇴장 규칙 트리거

사용자 지정 이벤트를 Journey 진입 또는 퇴장 규칙으로 설정하여 이벤트 발생 시 즉시 사용자를 추가하거나 제거하세요.

예시:

* `signup_completed` → 온보딩 시작 또는 체험 권유 Journey에서 제거
* `purchase` → 확인 및 크로스셀 전송 또는 장바구니 이탈 Journey에서 제거

<Card title="Journey 설정" icon="gear" href="./journeys-settings#entry-rules">
  사용자 지정 이벤트로 사용자를 Journeys에 진입시키세요.
</Card>

### Journey 흐름 제어 (Wait Until)

Wait Until 단계를 사용하여 사용자 지정 이벤트가 발생할 때까지 사용자를 대기시키세요.

예시:

* `added_to_cart` 이후 `purchase`까지 대기

<Info> 만료 기간을 정의할 수 있습니다. 사용자가 제시간에 이벤트를 트리거하지 않으면 대체 메시지를 보내거나 Journey를 종료할 수 있습니다. </Info>

<Card title="Journey Wait Until 단계" icon="stopwatch" href="./journeys-actions#wait-until">
  사용자 지정 이벤트가 발생할 때까지 사용자를 대기시키세요.
</Card>

### 이벤트 속성으로 Journeys 개인화

Journey 템플릿에서 Liquid를 사용하여 이벤트 속성을 참조하세요.

예시:

```liquid Liquid theme={null}
Thanks for purchasing {{ journey.first_event.properties.item }}!
```

<Card title="사용자 지정 이벤트 개인화" icon="bolt" href="./personalization-custom-event">
  이벤트 속성을 사용하여 Journeys를 개인화하는 전체 가이드.
</Card>

### 사용자 지정 이벤트로 사용자 세분화

사용자 지정 이벤트의 발생을 기반으로 세그먼트를 만드세요.

<Note>
  사용자 지정 이벤트 세분화는 Early Access 단계입니다.

  액세스를 요청하려면 다음을 포함하여 `support@onesignal.com`으로 이메일을 보내세요:

  * 회사 이름
  * OneSignal 앱 ID
</Note>

<Warning>
  현재 제한 사항:

  * 이메일 Warm Up 또는 A/B 테스트와 함께 사용할 수 없습니다
  * Journeys를 구동할 수 없습니다
  * 다른 세그먼트 필터와 결합할 수 없습니다
</Warning>

<Card title="세분화" icon="filter" href="./segmentation">
  세분화에 대한 전체 가이드.
</Card>

***

## 플랜 가용성 및 보존 비용

사용자 지정 이벤트는 모든 유료 플랜에서 사용할 수 있습니다.

<Card title="청구 FAQ" icon="receipt" href="./billing-faq#streaming-events">
  이벤트 보존 및 가격에 대해 알아보세요.
</Card>

***

## 태그 vs 사용자 지정 이벤트

[Tags](/docs/en/add-user-data-tags) and [Custom Events](/docs/en/custom-events) are both ways to add data to your users. However, there are some key differences:

| Feature        |                      Tags                     |                                          Custom Events                                         |
| -------------- | :-------------------------------------------: | :--------------------------------------------------------------------------------------------: |
| Data usage     |        Segmentation and personalization       | Trigger Journeys without a Segment, Wait Until steps, personalization directly within Journeys |
| Data retention |                    Lifetime                   |        30+ days ([lifetime storage is available](/docs/en/billing-faq#streaming-events))       |
| Data format    |          Key-value strings or numbers         |                                              JSON                                              |
| Data source    | OneSignal SDK, API, or integrations (limited) |                               OneSignal SDK, API, or integrations                              |
| Data access    |    Segmentation and message personalization   |        Journeys and Journey-message-template personalization, Segmentation (Coming soon)       |

The key distinction between Tags and Custom Events is in their depth and use cases. Tags are properties of a user, such as Name, Account Status, or Location. Events are thing that the user has done, such as Purchasing an Item, Completing a Level, or Inviting a Friend. Both tags and events can be used for segmentation and personalization.

In practice, you will likely use both:

* Tags for user properties that are static and don't change often
* Custom Events for real-time scenarios, complex segmentation, and more sophisticated journey workflows

***