이벤트 스트림

• 푸시 메시지 이벤트 (전송됨, 수신됨, 클릭됨, 실패, 구독 취소됨)
• 이메일 이벤트 (전송됨, 열람됨, 클릭됨, 반송됨, 구독 취소됨 등)
• SMS 이벤트 (전송됨, 실패, 구독 취소됨 등)
• 인앱 메시지 이벤트 (노출, 클릭됨 등)
• 라이브 활동 이벤트 (전송됨, 전달됨, 확인된 전달, 실패, 구독 취소됨, 클릭됨)

​

일반적인 사용 사례

• 참여 데이터 중앙 집중화 — CRM, CDP 또는 데이터 웨어하우스로 이벤트를 스트리밍하여 크로스채널 활동(열람, 클릭, 반송)이 분산된 도구 대신 한 곳에 저장되도록 합니다.
• 분석, 보고 및 규정 준수 — 트렌드 분석, 감사 또는 규제 기록 보관을 위해 모든 메시지 이벤트를 웨어하우스에 저장합니다.
• 이탈 모니터링 — 구독 취소, 반송, 해제를 자체 시스템에서 추적하여 리텐션 위험을 조기에 발견합니다.
• 외부 워크플로 트리거 — 사용자가 메시지를 열거나 클릭할 때 다른 도구에서 자동화를 실행합니다(예: 리드 점수 업데이트, 팔로업 시퀀스 시작).
• 배치 동기화 및 추가 통합 대체 — 이벤트에 실시간으로 반응하고 OneSignal을 대상에 직접 연결하여 중간 도구와 유지 관리 비용을 절감합니다.

​

기술 팀 시작 안내

1. 대상 및 범위 결정 — 이벤트를 어디에 보낼지(자체 API, 데이터 웨어하우스, CDP 등), 어떤 이벤트 유형을 스트리밍할지(푸시, 이메일, SMS, IAM, 라이브 활동), 엔드포인트 크기를 적절히 조정하기 위한 메시지 볼륨 추정값을 합의합니다.
2. HTTP 엔드포인트 설정 — POST 요청을 수락하는 공개적으로 접근 가능한 엔드포인트를 구축하거나 구성합니다. 응답 시간을 낮게 유지하기 위해 무거운 처리 없이 이벤트를 빠르게 기록해야 합니다. 성능 기대치와 엔드포인트가 뒤처질 때 어떻게 되는지에 대해서는 재시도 / 비활성화를 참조하세요.
3. OneSignal에서 이벤트 스트림 구성 — 데이터 > 이벤트 스트림에서 이벤트를 선택하고, URL과 인증 헤더를 설정하고, 이벤트 스트림 데이터 필드와 Liquid 구문을 사용하여 JSON 본문을 정의합니다.
4. 엔드투엔드 테스트 — 프로덕션 엔드포인트로 전환하기 전에 webhook.site를 사용하여 페이로드 형식과 헤더를 확인합니다(테스트 참조).

​

설정

• 공개적으로 접근 가능한 HTTP(S) 엔드포인트의 유효한 URL 또는 IP 주소
• URL 및 IP 주소는 공개적으로 라우팅 가능해야 합니다
• 도메인에는 인식된 최상위 도메인(예: “.com”, “.net”)이 포함되어야 합니다

​

이벤트 선택

​

이벤트 스트림 필터

​

이벤트 스트림 구성

​

인증 헤더

• Authorization 헤더: Authorization 헤더를 추가하세요. 여기서 YOUR_TOKEN은 시스템 또는 타사에서 제공합니다:
  • Basic {{YOUR_TOKEN}}
  • Bearer {{YOUR_TOKEN}}
  • ApiKey {{YOUR_API_KEY}}
• 사용자 지정 헤더: 다음과 같은 사용자 지정 헤더를 추가할 수도 있습니다:
  • X-API-Key: {{YOUR_API_KEY}}

​

구성 테스트

​

허용되지 않는 헤더

• content-length
• referer
• metadata-flavor
• x-google-metadata-request
• host
• x-onesignal*

​

본문

​

개인화

​

본문 예시

{
  "Event Data": {
    "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}}"
  },
  "Message Data": {
    "message.id": "{{ message.id }}",
    "message.name": "{{ message.name }}",
    "message.title": "{{ message.title.en }}",
    "message.contents": "{{ message.contents.en }}",
    "message.template_id": "{{ message.template_id }}",
    "message.url": "{{ message.url }}",
    "message.app_url": "{{ message.app_url }}",
    "message.web_url": "{{ message.web_url }}"
  }
}

​

JSON에서 Liquid 구문 사용

• 문자열 → 따옴표로 감싸야 합니다.
• 숫자 → 따옴표로 감싸지 않습니다.
• 객체 → 따옴표로 감싸지 않아야 합니다.

{
  "user_id": "{{ user.onesignal_id }}"
}

{
  "user_id": {{ user.onesignal_id }}
}

{
  "user_score": {{ user.tags.score }}
}

{
  "user_score": "{{ user.tags.score }}"
}

{
  "user_data": {{ user.tags }}
}

{
  "user_data": "{{ user.tags }}"
}

1. 직접 언어 확인 사용: 더 나은 호환성을 위해 userLang과 같은 변수가 아닌 조건부에서 항상 user.language를 직접 확인하세요.
2. 간단하게 시작: 기본 구문으로 시작한 다음 점진적으로 복잡성을 추가하세요.
3. 과도한 중첩 방지: 구문 분석 문제를 방지하기 위해 조건부를 평평하게 유지하세요.
4. 먼저 기본 구두점 테스트: 특수 문자를 사용하기 전에 간단한 문장과 구두점으로 시작하세요.
5. 대체 사용: 번역이 누락된 경우에 대비하여 기본 언어(예: 영어)를 확보하세요.
6. 표준 키 사용: 신뢰성을 위해 content/title/en과 같은 표준 OneSignal 키를 사용하세요.

​

결과 및 디버깅

​

재시도 / 비활성화

1. 앱 및 조직 관리자는 실패 볼륨이 상당해질 때(비활성화 전)와 스트림이 비활성화될 때 다시 이메일을 받습니다.
2. 대시보드의 이벤트 스트림 인덱스 페이지에도 배너가 표시됩니다.
3. 근본적인 문제를 수정하고 로그 탭 또는 webhook.site로 테스트한 후 스트림을 다시 활성화하세요.

• 이벤트를 빠르게 기록 — 무거운 인라인 처리 없이 수신 이벤트를 대기열이나 데이터 저장소에 씁니다.
• 느린 응답과 429 방지 — 일관된 느린 응답 시간이나 속도 제한 응답은 이벤트를 쌓이게 하여 OneSignal이 스트림을 비활성화하도록 합니다.
• 전송 볼륨에 맞게 크기 조정 — 100k 메시지를 보내면 선택한 이벤트 유형당 최대 100k 이벤트가 발생합니다. 플랜의 메시지 볼륨을 검토하고 적절히 프로비저닝하세요.

​

성공을 위한 팁

• 먼저 자체 서버에 스트림을 지정하세요. 서드파티 API에 직접 연결할 수 있지만, 수신 측을 제어하지 않으면 디버깅, 속도 제한 처리, 볼륨 관리가 더 어려워집니다.
• 서드파티로 전달하기 전에 버퍼링하세요. OneSignal은 사용자가 이벤트를 트리거하는 속도로 이벤트를 전송합니다 — 대규모 전송은 외부 속도 제한을 초과하거나 비용을 증가시키는 버스트를 생성할 수 있습니다(특히 SMS 제공업체). 이벤트를 수락하고, 대기열에 넣고, 제어할 수 있는 속도로 외부 API에 전달하는 경량 서비스를 구축하세요.
• 서드파티 API 문서를 확인하세요. 많은 서비스가 이벤트 스트림으로 대상으로 할 수 있는 공개 HTTP API를 제공합니다. 스트림을 구성하기 전에 인증, 허용된 페이로드 형식 및 속도 제한에 관한 문서를 찾아보세요.

​

메시지 이벤트 데이터 제한

​

테스트

• Host: 요청이 온 IP 주소입니다. 가능한 IP 목록은 REST API 개요를 참조하세요.
• Request Content 이벤트 스트림의 본문 내에서 전송된 데이터입니다.