메인 콘텐츠로 건너뛰기
Liquid 구문 사용을 통해 이벤트 스트림 데이터에 액세스합니다. 임의의 필드를 {{ }}로 감싸서 이벤트 스트림 본문에 포함합니다. 예시를 참조하세요.
Journeys 및 API 전송 메시지 데이터는 30일간 보관됩니다. 30일 이후에 발생한 인터랙션 이벤트(클릭, 열람, 구독 취소)는 메시지 속성이 비어 있을 수 있습니다. 데이터를 복원하려면 인터랙션 이벤트의 message.id를 전체 메시지 데이터를 포함한 원본 sent 이벤트와 연관시키세요.

​
event 속성

모든 이벤트에는 아래의 핵심 필드가 포함됩니다. event.data.*의 채널별 필드는 해당하는 경우에만 포함됩니다 — 채널별 필드를 참조하세요.
​
event.kind
string
채널과 액션을 결합한 이벤트 유형(예: message.push.clicked, message.email.bounced). 아래 이벤트 카인드 참조에서 전체 값 목록을 확인하세요. Liquid: {{ event.kind }}
​
event.id
UUID
UUID v4 형식의 각 개별 이벤트에 대한 고유한 OneSignal 생성 식별자. 멱등성 전달 추적에 이 ID를 사용하세요. 메시지 또는 템플릿 식별자는 message.id 또는 message.template_id를 사용하세요. Liquid: {{ event.id }}
​
event.timestamp
integer
이벤트의 UNIX 타임스탬프. Liquid: {{ event.timestamp }}
​
event.datetime
string
ISO 8601 문자열로 UTC 표시된 이벤트의 사람이 읽을 수 있는 시간(예: “2024-02-21T23:45:15.228Z”). Liquid: {{ event.datetime }}
​
event.app_id
UUID
OneSignal App ID. Liquid: {{ event.app_id }}
​
event.subscription_device_type
string
구독 유형(예: iOS, Android, Chrome, Email, SMS). Liquid: {{ event.subscription_device_type }}
​
event.subscription_id
UUID
OneSignal Subscription ID. Liquid: {{ event.subscription_id }}
​
event.onesignal_id
UUID
OneSignal User ID. Liquid: {{ event.onesignal_id }}
​
event.external_id
string
OneSignal External ID 별칭으로 설정된 사용자 ID. 설정되지 않은 경우 비어 있을 수 있습니다. Liquid: {{ event.external_id }}

​
채널별 필드

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

​
인앱 메시지 이벤트

message.iam.* 이벤트에 포함됩니다. 자세한 내용은 인앱 메시지 이벤트 스트림을 참조하세요.
​
event.data.page_name
string
표시된 인앱 메시지 페이지 또는 카드의 이름. Liquid: {{ event.data.page_name }}
​
event.data.page_id
string
표시된 인앱 메시지 페이지 또는 카드의 고유 식별자. Liquid: {{ event.data.page_id }}
​
event.data.target_name
string
클릭된 버튼 또는 이미지 블록 요소의 이름. 해당 요소에 인앱 클릭 액션이 포함되어야 합니다. Liquid: {{ event.data.target_name }}
​
event.data.target_id
string
클릭된 버튼 또는 이미지 블록 요소의 고유 식별자. Liquid: {{ event.data.target_id }}

​
Live Activity 이벤트

message.live_activity.* 이벤트에 포함됩니다.
​
event.data.live_activity_id
string
특정 Live Activity의 고유 식별자(예: “Knicks vs Cavs - Oct 22 7PM”). Liquid: {{ event.data.live_activity_id }}
​
event.data.live_activity_type
string
Live Activity 카테고리의 그룹화 레이블(예: “Knicks_games”). Liquid: {{ event.data.live_activity_type }}

​
실패 이벤트

message.push.failed 및 message.email.failed 이벤트에 포함됩니다.
​
event.data.failure_reason
string
메시지 전송 실패 이유. 일반적인 이유는 푸시 메시지 보고서 또는 이메일 메시지 보고서를 참조하세요. Liquid: {{ event.data.failure_reason }}

​
이벤트 카인드 참조

각 지표의 자세한 정의는 지표 용어집을 참조하세요.
메시지 이벤트 종류 (OneSignal)이벤트 이름 (데이터 세트)이벤트 설명
Push Sentmessage.push.sent푸시 알림이 푸시 서비스(FCM, APNS 등)로 성공적으로 전송되었습니다.
Push Receivedmessage.push.received수신자가 푸시 알림을 받았습니다. 모든 플랫폼에서 사용할 수 없습니다. 자세한 내용은 확인된 전달을 참조하세요.
Push Clickedmessage.push.clicked사용자가 푸시 알림을 탭하여 기기에서 앱을 열었습니다.
Push Failedmessage.push.failed푸시 전송에 실패했습니다. 자세한 내용은 푸시 메시지 리포트를 참조하세요.
Push Unsubscribedmessage.push.unsubscribed사용자가 푸시 구독을 취소했습니다. 푸시 구독 상태는 언제 업데이트되나요?를 참조하세요.
In-App Impressionmessage.iam.impression인앱 메시지가 기기에 성공적으로 표시되었습니다.
In-App Clickedmessage.iam.clicked사용자가 인앱 메시지의 요소를 탭했습니다.
In-App Page Displayedmessage.iam.page_displayed인앱 메시지 페이지가 표시되었습니다. 캐러셀 추적에 유용합니다.
Email Sentmessage.email.sent이메일이 성공적으로 전송되었습니다.
Email Receivedmessage.email.received수신자가 이메일을 받았습니다.
Email Openedmessage.email.opened수신자가 이메일을 열었습니다. 자세한 내용은 이메일 메시지 리포트를 참조하세요.
Email Link Clickedmessage.email.clicked사용자가 이메일의 링크를 탭했습니다.
Email Unsubscribedmessage.email.unsubscribed사용자가 구독 취소 링크를 통해 이메일 구독을 취소했습니다.
Email Reported As Spammessage.email.reported_as_spam사용자가 이메일을 스팸으로 신고했습니다. Gmail은 추적을 위해 Google Postmaster Tools가 필요합니다. 자세한 내용은 이메일 전달성을 참조하세요.
Email Bouncedmessage.email.bounced영구 오류로 인해 이메일이 발신자에게 반송되었습니다. 자세한 내용은 이메일 메시지 리포트를 참조하세요.
Email Failedmessage.email.failed이메일을 전달할 수 없습니다. 자세한 내용은 이메일 메시지 리포트를 참조하세요.
Email Suppressedmessage.email.suppressed이메일 주소가 차단 목록에 있기 때문에 이메일을 전송할 수 없습니다.
SMS Sentmessage.sms.sentSMS가 수신자에게 전송되었습니다.
SMS Failedmessage.sms.failedSMS 전송에 실패했습니다. 자세한 내용은 SMS 메시지 리포트를 참조하세요.
SMS Deliveredmessage.sms.deliveredSMS가 성공적으로 전달되었습니다.
SMS Undeliveredmessage.sms.undeliveredSMS를 전송할 수 없습니다. 자세한 내용은 SMS 메시지 리포트를 참조하세요.
Live Activity Sentmessage.live_activity.sentLive Activity가 FCM/APNS에 성공적으로 전송되었습니다.
Live Activity Deliveredmessage.live_activity.delivered수신자가 Live Activity를 수신했습니다.
Live Activity Unsubscribedmessage.live_activity.unsubscribed사용자가 Live Activities 구독을 취소했습니다.
Live Activity Failedmessage.live_activity.failedLive Activity 전송에 실패했습니다.
Live Activity Clickedmessage.live_activity.clicked사용자가 Live Activity를 클릭했습니다.

​
이벤트 객체 예시

이 Liquid 템플릿을 이벤트 스트림 본문에 복사하여 모든 이벤트 필드를 캡처하세요:
JSON
{
  "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 }}"
}
Liquid 렌더링 후 푸시 클릭 이벤트의 모습:
JSON
{
  "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과 같은 채널별 필드는 해당 필드를 포함하지 않는 이벤트 카인드에서는 비어 있습니다.

​
message 속성

message 객체는 최종 사용자에게 전송된 메시지(ID, 템플릿, 내용, URL 포함)를 설명합니다.
​
message.id
UUID
OneSignal에서 생성한 메시지 ID. Liquid: {{ message.id }}
​
message.name
string
대시보드에서 설정하거나 API name 속성을 사용하여 설정한 메시지 이름. Liquid: {{ message.name }}
​
message.title
object
푸시 메시지 제목 또는 이메일 제목. 푸시의 경우 {'en':'Your title'}와 같은 로컬라이즈된 객체를 반환합니다. 이메일의 경우 제목 줄을 일반 문자열로 반환합니다. 대시보드 또는 API headings / email_subject 속성으로 설정합니다. Liquid: {{ message.title }}
​
message.contents
object
푸시 또는 SMS 메시지 내용(50자로 잘림). 이메일 내용(email_body)은 제공되지 않습니다. 대시보드 또는 API contents 속성으로 설정합니다. Liquid: {{ message.contents }}
​
message.template_id
UUID
Journeys 또는 API template_id 속성을 통해 전송된 메시지의 템플릿 ID. Liquid: {{ message.template_id }}
​
message.url
string
웹 및 앱에 구애받지 않는 단일 URL을 사용하는 경우 메시지의 실행 URL. 자세한 내용은 URL, 링크 및 딥링크를 참조하세요. Liquid: {{ message.url }}
​
message.app_url
string
웹 및 앱별 URL을 별도로 사용하는 경우 앱별 실행 URL. 자세한 내용은 URL, 링크 및 딥링크를 참조하세요. Liquid: {{ message.app_url }}
​
message.web_url
string
웹 및 앱별 URL을 별도로 사용하는 경우 웹별 실행 URL. 자세한 내용은 URL, 링크 및 딥링크를 참조하세요. Liquid: {{ message.web_url }}
​
message.live_activity_event_kind
string
Live Activity 액션 유형: start, update, 또는 end. message.live_activity.* 이벤트에만 존재합니다. Liquid: {{ message.live_activity_event_kind }}

​
메시지 객체 예시

이 Liquid 템플릿을 이벤트 스트림 본문에 복사하여 모든 메시지 필드를 캡처하세요:
JSON
{
  "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 }}"
}
푸시 알림 메시지:
JSON
{
  "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
{
  "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": ""
}

​
user 속성

user 객체에는 메시지를 수신한 사용자의 프로필 수준 데이터가 포함됩니다.
​
user.onesignal_id
string
사용자의 OneSignal ID. Liquid: {{ user.onesignal_id }}
​
user.external_id
string
사용자의 External ID. Liquid: {{ user.external_id }}
​
user.tags
object
사용자의 태그. {{ user.tags }}로 전체 객체에 액세스하거나 {{ user.tags.your_tag }}로 특정 태그에 액세스합니다. 누락된 태그 처리를 위한 기본값: {{ user.tags.your_tag | default: '' }}.
​
user.language
string
사용자의 언어 코드. Liquid: {{ user.language }}

​
subscription 속성

이러한 속성은 메시지를 수신한 구독을 설명합니다.
​
user.subscription.id
string
구독의 OneSignal ID. Liquid: {{ user.subscription.id }}
​
user.subscription.app_id
string
OneSignal App ID. Liquid: {{ user.subscription.app_id }}
​
user.subscription.subscription_token
string
구독의 플랫폼별 토큰. 이메일의 경우 이메일 주소. SMS의 경우 E.164 형식의 전화번호. 푸시의 경우 푸시 토큰. Liquid: {{ user.subscription.subscription_token }}
​
user.subscription.session_count
number
이 구독에 기록된 총 세션 수. Liquid: {{ user.subscription.session_count }}
​
user.subscription.language
string
구독에 설정된 언어 코드. Liquid: {{ user.subscription.language }}
​
user.subscription.game_version
string
구독에서 보고한 앱 또는 게임 버전. Liquid: {{ user.subscription.game_version }}
​
user.subscription.last_active
number
구독의 가장 최근 세션의 UNIX 타임스탬프. Liquid: {{ user.subscription.last_active }}
​
user.subscription.play_time
number
이 구독에 기록된 총 플레이 시간(초). Liquid: {{ user.subscription.play_time }}
​
user.subscription.amount_spent
number
이 구독에 기록된 총 앱 내 구매 금액. Liquid: {{ user.subscription.amount_spent }}
​
user.subscription.created_at
number
구독이 생성된 시점의 UNIX 타임스탬프. Liquid: {{ user.subscription.created_at }}
​
user.subscription.subscribed
boolean
구독이 현재 옵트인 상태인지 여부. Liquid: {{ user.subscription.subscribed }}
​
user.subscription.sdk
string
구독 기기의 OneSignal SDK 버전. Liquid: {{ user.subscription.sdk }}
​
user.subscription.device_model
string
기기 하드웨어 모델(예: “iPhone14,2”, “Pixel 7”). Liquid: {{ user.subscription.device_model }}
​
user.subscription.device_os
string
기기 운영 체제 및 버전(예: “iOS 17.2”, “Android 14”). Liquid: {{ user.subscription.device_os }}

​
관련 페이지

Event Streams

Event Streams 설정 및 구성(설정, 본문 템플릿, 디버깅 포함).

Liquid 구문 사용

이벤트 스트림 본문 개인화에 사용되는 Liquid 구문 참조.

인앱 메시지 이벤트 스트림

인앱 메시지 이벤트 데이터 및 캐러셀 추적에 대한 세부 정보.

지표 용어집

채널 전체의 모든 메시지 이벤트 지표 정의.

​
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에는 메시지 이벤트(전송됨, 클릭됨, 열림, 반송됨 등)가 포함되며 커스텀 이벤트는 포함되지 않습니다. 커스텀 이벤트는 OneSignal 로 전송하는 사용자 액션입니다. Event Streams는 메시지 전달 및 참여 데이터를 OneSignal에서 내보냅니다.

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

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