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

# 이벤트 스트림 데이터 참조

> Event Streams 및 Webhooks에서 사용 가능한 모든 이벤트, 메시지, 사용자 및 구독 속성에 대한 스키마 참조로, 각 필드의 Liquid 구문 포함.

[Liquid 구문 사용](./using-liquid-syntax)을 통해 이벤트 스트림 데이터에 액세스합니다. 임의의 필드를 `{{ }}`로 감싸서 이벤트 스트림 본문에 포함합니다. [예시](./event-streams#example-body)를 참조하세요.

<Warning>
  Journeys 및 API 전송 메시지 데이터는 30일간 보관됩니다. 30일 이후에 발생한 인터랙션 이벤트(클릭, 열람, 구독 취소)는 메시지 속성이 비어 있을 수 있습니다. 데이터를 복원하려면 인터랙션 이벤트의 `message.id`를 전체 메시지 데이터를 포함한 원본 `sent` 이벤트와 연관시키세요.
</Warning>

## `event` 속성

모든 이벤트에는 아래의 핵심 필드가 포함됩니다. `event.data.*`의 채널별 필드는 해당하는 경우에만 포함됩니다 — [채널별 필드](#channel-specific-fields)를 참조하세요.

<ParamField body="event.kind" type="string">
  채널과 액션을 결합한 이벤트 유형(예: `message.push.clicked`, `message.email.bounced`). 아래 [이벤트 카인드 참조](#event-kind-reference)에서 전체 값 목록을 확인하세요. **Liquid:** `{{ event.kind }}`
</ParamField>

<ParamField body="event.id" type="UUID">
  UUID v4 형식의 각 개별 이벤트에 대한 고유한 OneSignal 생성 식별자. 멱등성 전달 추적에 이 ID를 사용하세요. 메시지 또는 템플릿 식별자는 [`message.id`](#message-id) 또는 [`message.template_id`](#template-id)를 사용하세요. **Liquid:** `{{ event.id }}`
</ParamField>

<ParamField body="event.timestamp" type="integer">
  이벤트의 UNIX 타임스탬프. **Liquid:** `{{ event.timestamp }}`
</ParamField>

<ParamField body="event.datetime" type="string">
  ISO 8601 문자열로 UTC 표시된 이벤트의 사람이 읽을 수 있는 시간(예: "2024-02-21T23:45:15.228Z"). **Liquid:** `{{ event.datetime }}`
</ParamField>

<ParamField body="event.app_id" type="UUID">
  OneSignal [App ID](./keys-and-ids). **Liquid:** `{{ event.app_id }}`
</ParamField>

<ParamField body="event.subscription_device_type" type="string">
  구독 유형(예: `iOS`, `Android`, `Chrome`, `Email`, `SMS`). **Liquid:** `{{ event.subscription_device_type }}`
</ParamField>

<ParamField body="event.subscription_id" type="UUID">
  OneSignal [Subscription ID](./subscriptions). **Liquid:** `{{ event.subscription_id }}`
</ParamField>

<ParamField body="event.onesignal_id" type="UUID">
  OneSignal [User ID](./users). **Liquid:** `{{ event.onesignal_id }}`
</ParamField>

<ParamField body="event.external_id" type="string">
  OneSignal [External ID](./users) 별칭으로 설정된 사용자 ID. 설정되지 않은 경우 비어 있을 수 있습니다. **Liquid:** `{{ event.external_id }}`
</ParamField>

### 채널별 필드

이러한 `event.data.*` 필드는 특정 이벤트 카인드에만 존재합니다.

#### 인앱 메시지 이벤트

`message.iam.*` 이벤트에 포함됩니다. 자세한 내용은 [인앱 메시지 이벤트 스트림](./iam-event-streams)을 참조하세요.

<ParamField body="event.data.page_name" type="string">
  표시된 인앱 메시지 페이지 또는 카드의 이름. **Liquid:** `{{ event.data.page_name }}`
</ParamField>

<ParamField body="event.data.page_id" type="string">
  표시된 인앱 메시지 페이지 또는 카드의 고유 식별자. **Liquid:** `{{ event.data.page_id }}`
</ParamField>

<ParamField body="event.data.target_name" type="string">
  클릭된 버튼 또는 이미지 블록 요소의 이름. 해당 요소에 [인앱 클릭 액션](./iam-click-actions)이 포함되어야 합니다. **Liquid:** `{{ event.data.target_name }}`
</ParamField>

<ParamField body="event.data.target_id" type="string">
  클릭된 버튼 또는 이미지 블록 요소의 고유 식별자. **Liquid:** `{{ event.data.target_id }}`
</ParamField>

#### Live Activity 이벤트

`message.live_activity.*` 이벤트에 포함됩니다.

<ParamField body="event.data.live_activity_id" type="string">
  특정 Live Activity의 고유 식별자(예: "Knicks vs Cavs - Oct 22 7PM"). **Liquid:** `{{ event.data.live_activity_id }}`
</ParamField>

<ParamField body="event.data.live_activity_type" type="string">
  Live Activity 카테고리의 그룹화 레이블(예: "Knicks\_games"). **Liquid:** `{{ event.data.live_activity_type }}`
</ParamField>

#### 실패 이벤트

`message.push.failed` 및 `message.email.failed` 이벤트에 포함됩니다.

<ParamField body="event.data.failure_reason" type="string">
  메시지 전송 실패 이유. 일반적인 이유는 [푸시 메시지 보고서](./push-notification-message-reports#failure-message-troubleshooting) 또는 [이메일 메시지 보고서](./email-message-reports#why-are-my-emails-marked-as-failed)를 참조하세요. **Liquid:** `{{ event.data.failure_reason }}`
</ParamField>

### 이벤트 카인드 참조

각 지표의 자세한 정의는 [지표 용어집](./analytics-metrics-glossary)을 참조하세요.

| 메시지 이벤트 종류 (OneSignal)     | 이벤트 이름 (데이터 세트)                      | 이벤트 설명                                                                                                                                              |
| -------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Push Sent                  | `message.push.sent`                  | 푸시 알림이 푸시 서비스(FCM, APNS 등)로 성공적으로 전송되었습니다.                                                                                                          |
| Push Received              | `message.push.received`              | 수신자가 푸시 알림을 받았습니다. 모든 플랫폼에서 사용할 수 없습니다. 자세한 내용은 [확인된 전달](./confirmed-delivery)을 참조하세요.                                                              |
| Push Clicked               | `message.push.clicked`               | 사용자가 푸시 알림을 탭하여 기기에서 앱을 열었습니다.                                                                                                                      |
| Push Failed                | `message.push.failed`                | 푸시 전송에 실패했습니다. 자세한 내용은 [푸시 메시지 리포트](./push-notification-message-reports)를 참조하세요.                                                                    |
| Push Unsubscribed          | `message.push.unsubscribed`          | 사용자가 푸시 [구독](./subscriptions)을 취소했습니다. [푸시 구독 상태는 언제 업데이트되나요?](./subscriptions#when-do-push-subscription-statuses-update%3F)를 참조하세요.                |
| In-App Impression          | `message.iam.impression`             | 인앱 메시지가 기기에 성공적으로 표시되었습니다.                                                                                                                          |
| In-App Clicked             | `message.iam.clicked`                | 사용자가 인앱 메시지의 요소를 탭했습니다.                                                                                                                             |
| In-App Page Displayed      | `message.iam.page_displayed`         | 인앱 메시지 페이지가 표시되었습니다. 캐러셀 추적에 유용합니다.                                                                                                                 |
| Email Sent                 | `message.email.sent`                 | 이메일이 성공적으로 전송되었습니다.                                                                                                                                 |
| Email Received             | `message.email.received`             | 수신자가 이메일을 받았습니다.                                                                                                                                    |
| Email Opened               | `message.email.opened`               | 수신자가 이메일을 열었습니다. 자세한 내용은 [이메일 메시지 리포트](./email-message-reports)를 참조하세요.                                                                             |
| Email Link Clicked         | `message.email.clicked`              | 사용자가 이메일의 링크를 탭했습니다.                                                                                                                                |
| Email Unsubscribed         | `message.email.unsubscribed`         | 사용자가 [구독 취소 링크](./unsubscribe-links-email-subscriptions)를 통해 이메일 구독을 취소했습니다.                                                                        |
| Email Reported As Spam     | `message.email.reported_as_spam`     | 사용자가 이메일을 스팸으로 신고했습니다. Gmail은 추적을 위해 [Google Postmaster Tools](./google-postmaster-tools)가 필요합니다. 자세한 내용은 [이메일 전달성](./email-deliverability)을 참조하세요. |
| Email Bounced              | `message.email.bounced`              | 영구 오류로 인해 이메일이 발신자에게 반송되었습니다. 자세한 내용은 [이메일 메시지 리포트](./email-message-reports)를 참조하세요.                                                                |
| Email Failed               | `message.email.failed`               | 이메일을 전달할 수 없습니다. 자세한 내용은 [이메일 메시지 리포트](./email-message-reports)를 참조하세요.                                                                             |
| Email Suppressed           | `message.email.suppressed`           | 이메일 주소가 [차단 목록](./email-deliverability)에 있기 때문에 이메일을 전송할 수 없습니다.                                                                                    |
| SMS Sent                   | `message.sms.sent`                   | SMS가 수신자에게 전송되었습니다.                                                                                                                                 |
| SMS Failed                 | `message.sms.failed`                 | SMS 전송에 실패했습니다. 자세한 내용은 [SMS 메시지 리포트](./sms-message-reports)를 참조하세요.                                                                                |
| SMS Delivered              | `message.sms.delivered`              | SMS가 성공적으로 전달되었습니다.                                                                                                                                 |
| SMS Undelivered            | `message.sms.undelivered`            | SMS를 전송할 수 없습니다. 자세한 내용은 [SMS 메시지 리포트](./sms-message-reports)를 참조하세요.                                                                               |
| Live Activity Sent         | `message.live_activity.sent`         | Live Activity가 FCM/APNS에 성공적으로 전송되었습니다.                                                                                                             |
| Live Activity Delivered    | `message.live_activity.delivered`    | 수신자가 Live Activity를 수신했습니다.                                                                                                                         |
| Live Activity Unsubscribed | `message.live_activity.unsubscribed` | 사용자가 Live Activities 구독을 취소했습니다.                                                                                                                    |
| Live Activity Failed       | `message.live_activity.failed`       | Live Activity 전송에 실패했습니다.                                                                                                                           |
| Live Activity Clicked      | `message.live_activity.clicked`      | 사용자가 Live Activity를 클릭했습니다.                                                                                                                         |

### 이벤트 객체 예시

이 Liquid 템플릿을 이벤트 스트림 본문에 복사하여 모든 이벤트 필드를 캡처하세요:

```json JSON theme={null}
{
  "event.kind": "{{ event.kind }}",
  "event.id": "{{ event.id }}",
  "event.timestamp": "{{ event.timestamp }}",
  "event.datetime": "{{ event.datetime }}",
  "event.app_id": "{{ event.app_id }}",
  "event.subscription_device_type": "{{ event.subscription_device_type }}",
  "event.subscription_id": "{{ event.subscription_id }}",
  "event.onesignal_id": "{{ event.onesignal_id }}",
  "event.external_id": "{{ event.external_id }}",
  "event.data.page_name": "{{ event.data.page_name }}",
  "event.data.page_id": "{{ event.data.page_id }}",
  "event.data.target_name": "{{ event.data.target_name }}",
  "event.data.target_id": "{{ event.data.target_id }}",
  "event.data.failure_reason": "{{ event.data.failure_reason }}"
}
```

<Accordion title="렌더링 출력 예시">
  Liquid 렌더링 후 푸시 클릭 이벤트의 모습:

  ```json JSON theme={null}
  {
    "event.kind": "message.push.clicked",
    "event.id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "event.timestamp": 1708559115,
    "event.datetime": "2024-02-21T23:45:15.228Z",
    "event.app_id": "your-onesignal-app-id",
    "event.subscription_device_type": "iOS",
    "event.subscription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "event.onesignal_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "event.external_id": "user_12345",
    "event.data.page_name": "",
    "event.data.page_id": "",
    "event.data.target_name": "",
    "event.data.target_id": "",
    "event.data.failure_reason": ""
  }
  ```

  `event.data.page_name`과 같은 채널별 필드는 해당 필드를 포함하지 않는 이벤트 카인드에서는 비어 있습니다.
</Accordion>

***

## `message` 속성

`message` 객체는 최종 사용자에게 전송된 메시지(ID, 템플릿, 내용, URL 포함)를 설명합니다.

<ParamField body="message.id" type="UUID">
  OneSignal에서 생성한 메시지 ID. **Liquid:** `{{ message.id }}`
</ParamField>

<ParamField body="message.name" type="string">
  대시보드에서 설정하거나 API `name` 속성을 사용하여 설정한 메시지 이름. **Liquid:** `{{ message.name }}`
</ParamField>

<ParamField body="message.title" type="object">
  푸시 메시지 제목 또는 이메일 제목. 푸시의 경우 `{'en':'Your title'}`와 같은 로컬라이즈된 객체를 반환합니다. 이메일의 경우 제목 줄을 일반 문자열로 반환합니다. 대시보드 또는 API `headings` / `email_subject` 속성으로 설정합니다. **Liquid:** `{{ message.title }}`
</ParamField>

<ParamField body="message.contents" type="object">
  푸시 또는 SMS 메시지 내용(50자로 잘림). 이메일 내용(`email_body`)은 제공되지 않습니다. 대시보드 또는 API `contents` 속성으로 설정합니다. **Liquid:** `{{ message.contents }}`
</ParamField>

<ParamField body="message.template_id" type="UUID">
  Journeys 또는 API `template_id` 속성을 통해 전송된 메시지의 템플릿 ID. **Liquid:** `{{ message.template_id }}`
</ParamField>

<ParamField body="message.url" type="string">
  웹 및 앱에 구애받지 않는 단일 URL을 사용하는 경우 메시지의 실행 URL. 자세한 내용은 [URL, 링크 및 딥링크](./links)를 참조하세요. **Liquid:** `{{ message.url }}`
</ParamField>

<ParamField body="message.app_url" type="string">
  웹 및 앱별 URL을 별도로 사용하는 경우 앱별 실행 URL. 자세한 내용은 [URL, 링크 및 딥링크](./links)를 참조하세요. **Liquid:** `{{ message.app_url }}`
</ParamField>

<ParamField body="message.web_url" type="string">
  웹 및 앱별 URL을 별도로 사용하는 경우 웹별 실행 URL. 자세한 내용은 [URL, 링크 및 딥링크](./links)를 참조하세요. **Liquid:** `{{ message.web_url }}`
</ParamField>

<ParamField body="message.live_activity_event_kind" type="string">
  Live Activity 액션 유형: `start`, `update`, 또는 `end`. `message.live_activity.*` 이벤트에만 존재합니다. **Liquid:** `{{ message.live_activity_event_kind }}`
</ParamField>

### 메시지 객체 예시

이 Liquid 템플릿을 이벤트 스트림 본문에 복사하여 모든 메시지 필드를 캡처하세요:

```json JSON theme={null}
{
  "message.id": "{{ message.id }}",
  "message.name": "{{ message.name }}",
  "message.title": "{{ message.title }}",
  "message.contents": "{{ message.contents }}",
  "message.template_id": "{{ message.template_id }}",
  "message.url": "{{ message.url }}",
  "message.app_url": "{{ message.app_url }}",
  "message.web_url": "{{ message.web_url }}"
}
```

<Accordion title="렌더링 출력 예시">
  푸시 알림 메시지:

  ```json JSON theme={null}
  {
    "message.id": "f3c9cd09-10d7-4f59-b9bc-66e16607f1d5",
    "message.name": "weekly-promo-push",
    "message.title": "{'en':'Flash Sale: 50% Off Today'}",
    "message.contents": "{'en':'Shop now and save on select items'}",
    "message.template_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message.url": "https://example.com/sale",
    "message.app_url": "",
    "message.web_url": ""
  }
  ```

  이메일 메시지 — `message.title`은 일반 문자열로 된 제목 줄이며, `message.contents`는 이메일 본문 내용이 이벤트 스트림 데이터에 포함되지 않으므로 비어 있습니다:

  ```json JSON theme={null}
  {
    "message.id": "e2d3c4b5-a6f7-8901-bcde-f12345678901",
    "message.name": "onboarding-welcome-email",
    "message.title": "Welcome to Acme — here's how to get started",
    "message.contents": "",
    "message.template_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "message.url": "",
    "message.app_url": "",
    "message.web_url": ""
  }
  ```
</Accordion>

***

## `user` 속성

`user` 객체에는 메시지를 수신한 사용자의 프로필 수준 데이터가 포함됩니다.

<ParamField body="user.onesignal_id" type="string">
  사용자의 OneSignal ID. **Liquid:** `{{ user.onesignal_id }}`
</ParamField>

<ParamField body="user.external_id" type="string">
  사용자의 External ID. **Liquid:** `{{ user.external_id }}`
</ParamField>

<ParamField body="user.tags" type="object">
  사용자의 [태그](./add-user-data-tags). `{{ user.tags }}`로 전체 객체에 액세스하거나 `{{ user.tags.your_tag }}`로 특정 태그에 액세스합니다. 누락된 태그 처리를 위한 기본값: `{{ user.tags.your_tag | default: '' }}`.
</ParamField>

<ParamField body="user.language" type="string">
  사용자의 언어 코드. **Liquid:** `{{ user.language }}`
</ParamField>

***

## `subscription` 속성

이러한 속성은 메시지를 수신한 [구독](./subscriptions)을 설명합니다.

<ParamField body="user.subscription.id" type="string">
  구독의 OneSignal ID. **Liquid:** `{{ user.subscription.id }}`
</ParamField>

<ParamField body="user.subscription.app_id" type="string">
  OneSignal App ID. **Liquid:** `{{ user.subscription.app_id }}`
</ParamField>

<ParamField body="user.subscription.subscription_token" type="string">
  구독의 플랫폼별 토큰. **이메일**의 경우 이메일 주소. **SMS**의 경우 E.164 형식의 전화번호. **푸시**의 경우 푸시 토큰. **Liquid:** `{{ user.subscription.subscription_token }}`
</ParamField>

<ParamField body="user.subscription.session_count" type="number">
  이 구독에 기록된 총 세션 수. **Liquid:** `{{ user.subscription.session_count }}`
</ParamField>

<ParamField body="user.subscription.language" type="string">
  구독에 설정된 언어 코드. **Liquid:** `{{ user.subscription.language }}`
</ParamField>

<ParamField body="user.subscription.game_version" type="string">
  구독에서 보고한 앱 또는 게임 버전. **Liquid:** `{{ user.subscription.game_version }}`
</ParamField>

<ParamField body="user.subscription.last_active" type="number">
  구독의 가장 최근 세션의 UNIX 타임스탬프. **Liquid:** `{{ user.subscription.last_active }}`
</ParamField>

<ParamField body="user.subscription.play_time" type="number">
  이 구독에 기록된 총 플레이 시간(초). **Liquid:** `{{ user.subscription.play_time }}`
</ParamField>

<ParamField body="user.subscription.amount_spent" type="number">
  이 구독에 기록된 총 앱 내 구매 금액. **Liquid:** `{{ user.subscription.amount_spent }}`
</ParamField>

<ParamField body="user.subscription.created_at" type="number">
  구독이 생성된 시점의 UNIX 타임스탬프. **Liquid:** `{{ user.subscription.created_at }}`
</ParamField>

<ParamField body="user.subscription.subscribed" type="boolean">
  구독이 현재 옵트인 상태인지 여부. **Liquid:** `{{ user.subscription.subscribed }}`
</ParamField>

<ParamField body="user.subscription.sdk" type="string">
  구독 기기의 OneSignal SDK 버전. **Liquid:** `{{ user.subscription.sdk }}`
</ParamField>

<ParamField body="user.subscription.device_model" type="string">
  기기 하드웨어 모델(예: "iPhone14,2", "Pixel 7"). **Liquid:** `{{ user.subscription.device_model }}`
</ParamField>

<ParamField body="user.subscription.device_os" type="string">
  기기 운영 체제 및 버전(예: "iOS 17.2", "Android 14"). **Liquid:** `{{ user.subscription.device_os }}`
</ParamField>

***

## 관련 페이지

<Columns cols={2}>
  <Card title="Event Streams" icon="bolt" href="./event-streams">
    Event Streams 설정 및 구성(설정, 본문 템플릿, 디버깅 포함).
  </Card>

  <Card title="Liquid 구문 사용" icon="code" href="./using-liquid-syntax">
    이벤트 스트림 본문 개인화에 사용되는 Liquid 구문 참조.
  </Card>

  <Card title="인앱 메시지 이벤트 스트림" icon="message" href="./iam-event-streams">
    인앱 메시지 이벤트 데이터 및 캐러셀 추적에 대한 세부 정보.
  </Card>

  <Card title="지표 용어집" icon="chart-bar" href="./analytics-metrics-glossary">
    채널 전체의 모든 메시지 이벤트 지표 정의.
  </Card>
</Columns>

***

## FAQ

### 일부 이벤트 데이터가 누락되거나 비어 있는 이유는 무엇인가요?

Journeys 및 API 전송 메시지 데이터는 30일간 보관됩니다. 사용자가 메시지 전송 후 30일 이상 경과 후 인터랙션(클릭, 열람, 구독 취소)을 수행하면 관련 메시지 속성이 비어 있을 수 있습니다. 이를 해결하려면 인터랙션 이벤트의 `message.id`를 전체 메시지 데이터를 포함한 원본 `sent` 이벤트와 연관시키세요.

### `event.id`와 `message.id`의 차이점은 무엇인가요?

`event.id`는 개별 이벤트의 고유 식별자입니다(예: 특정 한 번의 클릭). `message.id`는 전송된 메시지의 식별자입니다 — 여러 이벤트가 동일한 `message.id`를 공유할 수 있습니다(예: 동일한 푸시 알림의 `sent` 이벤트와 `clicked` 이벤트).

### 푸시와 이메일에 대한 `message.title` 형식은 어떻게 되나요?

푸시 알림의 경우 `message.title`은 `{'en':'Your title'}`와 같은 로컬라이즈된 객체를 반환합니다. 이메일의 경우 제목 줄을 일반 문자열로 반환합니다. 형식은 채널에 따라 다릅니다.

### 커스텀 이벤트가 Event Streams에 포함되나요?

아니요. Event Streams에는 **메시지 이벤트**(전송됨, 클릭됨, 열림, 반송됨 등)가 포함되며 [커스텀 이벤트](./custom-events)는 포함되지 않습니다. 커스텀 이벤트는 OneSignal *로* 전송하는 사용자 액션입니다. Event Streams는 메시지 전달 및 참여 데이터를 OneSignal에서 *내보냅니다*.

### 이벤트 스트림 본문에서 특정 태그를 참조하려면 어떻게 하나요?

정확한 태그 키로 `{{ user.tags.your_tag_key }}`를 사용하세요. 태그가 설정되지 않은 경우 오류를 방지하려면 기본값을 추가하세요: `{{ user.tags.your_tag_key | default: '' }}`. 자세한 내용은 [Liquid 구문 사용](./using-liquid-syntax)을 참조하세요.

***