사용자 지정 이벤트

사용자 지정 이벤트란?

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

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

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

Journey 시작
Wait Until 단계로 Journey 진행
Journey에서 사용자 퇴장
이벤트 속성을 사용한 메시지 개인화
전환을 측정하고 이를 유도한 메시지에 귀속
행동 기반 사용자 세분화 (Early Access)

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

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

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

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

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

사용자 지정 이벤트는 특정 시점에 발생한 사건을 나타냅니다. 태그와 달리 사용자 프로필을 영구적으로 업데이트하지 않으며, 행동을 기록합니다.자세한 비교는 아래의 태그 vs 사용자 지정 이벤트를 참조하세요.

사용자 지정 이벤트 구조

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

string

필수

이벤트 이름. 최대 512 바이트. 이름은 바이트 단위로 측정되므로, 멀티바이트 문자로 이루어진 이름은 글자 수로 예상하는 것보다 더 빨리 제한에 도달합니다.

object

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

string

사용자의 External ID. Create Custom Events API를 사용할 때 사용자 식별자가 필요합니다. external_id 또는 onesignal_id 중 하나를 제공해야 합니다.

string

이벤트가 발생했거나 발생할 시간으로, ISO 8601 문자열 형식입니다. Create Custom Events API를 참조하세요.

string

중복 이벤트 처리를 방지하기 위한 고유 UUID입니다. Create Custom Events API를 참조하세요.

이벤트 크기 제한:

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

이벤트 이름 제한

각 앱은 최대 1,000개의 고유한 사용자 지정 이벤트 이름을 전송할 수 있습니다. 앱에서 이미 사용 중인 이름으로 전송된 이벤트는 항상 수락되므로, 제한에 도달해도 이미 전송 중인 이벤트가 중단되는 일은 없습니다. 앱이 1,000개의 이름에 도달하면 새로운 이름으로 전송된 이벤트는 거부됩니다. OneSignal은 요청 전체가 아니라 개별 이벤트를 거부하므로, 같은 배치의 다른 이벤트는 정상적으로 처리됩니다. API는 errors 배열과 함께 HTTP 202를 반환하며, 거부된 각 이벤트에는 오류 코드 too many event names가 포함됩니다. 거부된 이벤트는 저장되지 않고, 청구되지 않으며, Journey를 트리거하거나 메시지를 개인화하거나 세그먼트에 사용할 수 없습니다. 다만 Data > Events & Conversions에는 “This app has reached its limit of unique event names”라는 사유와 함께 실패로 표시되므로, 어떤 이름이 거부되었는지 확인할 수 있습니다. 공간을 확보하려면 더 이상 사용하지 않는 사용자 지정 이벤트 이름을 삭제하세요. 이름을 삭제하면 해당 슬롯이 확보되고, 그 이름으로 저장된 이벤트가 영구적으로 삭제됩니다.

Custom Events 페이지는 이벤트가 거부되기 전에, 앱의 고유 이벤트 이름이 900개를 넘어서면 경고를 표시합니다.

이름 제한은 OneSignal이 각 이벤트를 얼마나 오래 보관하는지와는 별개입니다. 보존에 대해서는 사용자 지정 이벤트 저장 및 보존을 참조하세요.

제한에 도달하지 않도록 이벤트 이름 지정하기

이벤트 이름은 무슨 일이 일어났는지를 나타냅니다. 변하는 값은 모두 속성에 넣어야 합니다. ID, 가격 또는 기타 가변 값을 이름에 넣으면 전송할 때마다 새로운 고유 이름이 생성되어 1,000개 제한을 빠르게 소진하게 됩니다.

{
  "name": "purchase_completed",
  "properties": { "product_id": "SKU-4412", "price": 24.99, "currency": "USD" }
}

{
  "name": "purchase_completed_SKU-4412_24.99"
}

속성은 Journeys, 전환, 세그먼트에서 사용할 수 있습니다.

이벤트 이름을 삭제하여 슬롯 확보하기

사용자 지정 이벤트 이름을 삭제하면 해당 슬롯이 확보되고, 그 이름으로 저장된 이벤트가 영구적으로 삭제됩니다. 이 작업은 되돌릴 수 없습니다.

더 이상 사용하지 않는 이벤트 찾기

Data > Events & Conversions로 이동하여 Event List 탭을 엽니다. 이벤트를 선택하면 세부 보기가 열립니다. Usage 패널에는 해당 이벤트를 참조하는 모든 Journey와 세그먼트가 표시되며, 마지막 발생 타임스탬프를 통해 이벤트가 여전히 유입되고 있는지 확인할 수 있습니다.

이벤트를 아직 사용 중인 모든 곳에서 제거하기

Usage 아래에 표시된 이벤트는 사용 중인 이벤트입니다. 먼저 해당 Journeys와 세그먼트를 업데이트하거나 제거하세요. 그렇지 않으면 이름을 삭제할 때 해당 동작에 영향을 미칩니다.

이름 삭제하기

이벤트 이름 옆의 행 메뉴를 열고 Delete를 선택한 다음 확인합니다. 사용자 지정 이벤트를 삭제하려면 권한이 필요합니다. 해당 옵션이 보이지 않으면 계정에서 해당 권한을 부여하는 역할을 가진 사람에게 요청하세요.

페이지 새로고침하기

삭제는 백그라운드에서 실행되며 몇 분 정도 걸릴 수 있습니다. 페이지는 자동으로 업데이트되지 않으므로 Refresh List를 선택하여 이름이 삭제되고 슬롯이 확보되었는지 확인하세요.

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

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

API 및 SDK

Create Custom Events API

백엔드에서 이벤트를 전송합니다.

Mobile/Web SDKs

클라이언트 측에서 이벤트를 추적합니다.

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

JSON

{
  "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"
    },
    {
      "name": "add_to_cart",
      "properties": {
        "item": "Hoodie",
        "size": "medium",
        "color": "black",
        "price": 49.99
      },
      "external_id": "user_12345",
      "timestamp": "2025-10-21T19:12:10.000Z",
      "idempotency_key": "789a0123-b45c-67d8-e901-234567890abc"
    },
    {
      "name": "signup_completed",
      "properties": {
        "plan": "pro",
        "trial": true
      },
      "external_id": "user_67890",
      "timestamp": "2025-10-21T19:15:44.000Z",
      "idempotency_key": "def01234-5678-90ab-cdef-012345678901"
    }
  ]
}

통합

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

Twilio Segment

Segment와 OneSignal 간에 이벤트와 오디언스를 라우팅합니다.

Amplitude

코호트를 동기화하고 Amplitude에서 커스텀 이벤트를 가져옵니다.

Snowflake

Snowflake 웨어하우스에서 커스텀 이벤트를 가져옵니다.

Google BigQuery

BigQuery 데이터셋에서 커스텀 이벤트를 가져옵니다.

Apache Kafka

Kafka 토픽에서 커스텀 이벤트를 스트리밍합니다.

모든 커스텀 이벤트 소스 보기

OneSignal로 커스텀 이벤트를 가져오는 데이터베이스, 웨어하우스, 스트리밍 플랫폼의 전체 목록을 확인하세요.

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

이벤트 수신 확인

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

Event List 탭

Event List 탭은 이벤트 이름별로 정리된 앱의 모든 사용자 지정 이벤트 개요를 제공합니다. 각 이벤트 유형에 대해 다음을 확인할 수 있습니다:

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

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

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

Event Activity 탭

Event Activity 탭은 OneSignal 앱에 수집된 가장 최근 이벤트의 라이브 피드를 제공합니다. 다음과 같이 활용할 수 있습니다:

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

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

사용자 지정 이벤트는 Custom Events 페이지에 즉시 표시됩니다. 하지만 사용자 프로필의 Activity Timeline > Custom Events에 이벤트가 표시되기까지는 최대 5분이 걸릴 수 있습니다. Custom Events 페이지는 최근 수집을 반영하는 반면, 사용자 프로필은 장기 저장소를 기반으로 하기 때문입니다.

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

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

Journey 진입 및 퇴장 규칙 트리거

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

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

Journey 설정

사용자 지정 이벤트로 사용자를 Journeys에 진입시키세요.

Journey 흐름 제어 (Wait Until)

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

added_to_cart 이후 purchase까지 대기

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

Journey Wait Until 단계

사용자 지정 이벤트가 발생할 때까지 사용자를 대기시키세요.

이벤트 속성으로 Journeys 개인화

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

Liquid

Thanks for purchasing {{ journey.first_event.properties.item }}!

사용자 지정 이벤트 개인화

이벤트 속성을 사용하여 Journeys를 개인화하는 전체 가이드.

전환 측정

사용자 지정 이벤트를 전환 지표로 정의하여 메시징의 비즈니스 영향을 측정하세요. OneSignal은 크로스 채널 마지막 터치 귀속 모델을 사용하여 전환을 이를 유도한 푸시, 이메일, SMS, 인앱, RCS 메시지에 귀속시킵니다. Settings > Analytics > Conversion Metrics에서 설정하며, 여기에서 이벤트 측정 방법을 선택합니다:

Count는 이벤트가 발생한 횟수를 추적합니다(예: 구매 15건).
Value는 숫자 이벤트 속성의 합계를 계산합니다(예: price 속성 기준 수익 $1,250).

전환은 전역 전환 대시보드와 메시지, 템플릿, Journey 보고서에 표시됩니다.

이벤트가 전환으로 계산되는지 여부는 보존 설정과 무관합니다. 이벤트가 저장되지 않도록 보존이 설정되어 있어도 이벤트는 전환 지표에 계산될 수 있습니다.

전환 지표

귀속 기간, 귀속 모델 및 설정 방법.

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

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

사용자 지정 이벤트 세분화는 Early Access 단계입니다.액세스를 요청하려면 다음을 포함하여 support@onesignal.com으로 이메일을 보내세요:

회사 이름
OneSignal 앱 ID

현재 제한 사항:

이메일 Warm Up 또는 A/B 테스트와 함께 사용할 수 없습니다
사용자 지정 이벤트 세그먼트는 사용자 기반입니다. 사용자 기반인 Journeys 외부에서 메시지를 보낼 때 포함 또는 제외 목적으로 구독 기반 세그먼트와 결합할 수 없습니다.
시간 기반 필터(“지난 X일 이내에 발생함”)는 이벤트가 원래 발생한 시점이 아니라 OneSignal이 이벤트를 수신한 시점을 기준으로 합니다. 과거 이벤트를 가져오고 있고 원래 이벤트 시간으로 세분화해야 하는 경우, 태그를 사용하여 이벤트 시간을 unix 타임스탬프로 저장하세요. 태그 필터는 동적 시간 기반 비교를 위한 “Time Elapsed” 연산자를 지원합니다. 태그는 사용자 수준이므로 가장 최근 값만 저장된다는 점에 유의하세요.

세분화

세분화에 대한 전체 가이드.

플랜 가용성 및 보존 비용

사용자 지정 이벤트는 모든 유료 플랜에서 사용할 수 있습니다. 이벤트 전송은 무료입니다. OneSignal은 저장하는 이벤트에 대해서만 요금을 청구하며, 저장된 이벤트는 세그먼트와 사용자 프로필에 필요합니다.

사용자 지정 이벤트 저장 및 보존

저장을 켜고, 이벤트별로 보존 기간을 설정하고, 저장된 이벤트를 관리하세요.

청구 FAQ

이벤트 저장이 청구서에 표시되는 방식.

태그 vs 사용자 지정 이벤트

태그와 사용자 지정 이벤트는 모두 사용자에게 데이터를 추가하는 방법입니다. 하지만 몇 가지 주요 차이점이 있습니다:

기능	태그	사용자 지정 이벤트
데이터 사용	세분화 및 개인화	세그먼트 없이 Journeys 트리거, Wait Until 단계, Journeys 내에서 직접 개인화
데이터 보존	영구	무제한(최소 30일)
데이터 형식	키-값 문자열 또는 숫자	JSON
데이터 소스	OneSignal SDK, API 또는 CSV 가져오기	OneSignal SDK, API 또는 통합
데이터 액세스	세분화 및 메시지 개인화	Journeys 및 Journey 메시지 템플릿 개인화, 세분화(출시 예정)

태그와 사용자 지정 이벤트의 주요 차이점은 그 깊이와 사용 사례에 있습니다. 태그는 이름, 계정 상태, 위치와 같은 사용자의 속성입니다. 이벤트는 상품 구매, 레벨 완료, 친구 초대와 같이 사용자가 수행한 행동입니다. 태그와 이벤트 모두 세분화와 개인화에 사용할 수 있습니다. 실제로는 두 가지를 모두 사용하게 될 가능성이 높습니다:

정적이고 자주 변경되지 않는 사용자 속성에는 태그
실시간 시나리오, 복잡한 세분화, 더 정교한 Journey 워크플로에는 사용자 지정 이벤트

​사용자 지정 이벤트란?

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

​사용자 지정 이벤트 구조

​이벤트 이름 제한

​제한에 도달하지 않도록 이벤트 이름 지정하기

​이벤트 이름을 삭제하여 슬롯 확보하기

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

​API 및 SDK

Create Custom Events API

Mobile/Web SDKs

​통합

Twilio Segment

Amplitude

Snowflake

Google BigQuery

Apache Kafka

모든 커스텀 이벤트 소스 보기

​이벤트 수신 확인

​Event List 탭

​Event Activity 탭

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

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

Journey 설정

​Journey 흐름 제어 (Wait Until)

Journey Wait Until 단계

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

사용자 지정 이벤트 개인화

​전환 측정

전환 지표

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

세분화

​플랜 가용성 및 보존 비용

사용자 지정 이벤트 저장 및 보존

청구 FAQ

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

사용자 지정 이벤트란?

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

사용자 지정 이벤트 구조

이벤트 이름 제한

제한에 도달하지 않도록 이벤트 이름 지정하기

이벤트 이름을 삭제하여 슬롯 확보하기

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

API 및 SDK

통합

이벤트 수신 확인

Event List 탭

Event Activity 탭

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

Journey 진입 및 퇴장 규칙 트리거

Journey 흐름 제어 (Wait Until)

이벤트 속성으로 Journeys 개인화

전환 측정

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

플랜 가용성 및 보존 비용

태그 vs 사용자 지정 이벤트