OneSignal 사용자 식별·이벤트 명세 키트

OneSignal User는 사용자 프로필이고 Subscription은 기기나 이메일 등 채널의 수신 단위입니다. 서비스의 안정적인 회원 ID를 External ID로 연결하면 여러 기기와 채널의 관계를 다룰 수 있습니다. 업무 시스템의 user_id, OneSignal의 사용자 ID, Subscription ID를 같은 열에 섞어 적지 않습니다. OneSignal Users

한 조직에 여러 사람이 속하는 서비스에서는 workspace_id를 External ID로 사용하지 않습니다. 이 키는 조직을 식별하며 사람을 구분하지 못합니다. 내부 회원의 user_id를 기준으로 정하고 조직·초대·작업의 관계는 별도의 업무 상관키로 관리합니다. 연동 가이드와 도입 점검표를 바탕으로 기존 로그인과 회원 데이터의 연결부터 확인합니다.

인증한 회원의 안정적인 ID가 준비되면 OneSignal.login으로 사용자 관계를 연결합니다. Web SDK의 logout은 현재 브라우저의 식별 관계를 해제해 익명 맥락으로 바꿉니다. 다른 기기의 구독이나 전체 회원 정보를 삭제하는 작업이 아닙니다. OneSignal Web SDK reference

서비스 회원가입, SDK 데이터 수집 설정, 마케팅 동의, 운영체제 알림 권한, 채널 구독 상태는 서로 다른 항목입니다. 가입 성공이나 login 성공으로 나머지 항목을 허용 상태로 바꾸지 않습니다. 각 상태를 갱신하는 원본과 담당, 발송 대상에서 제외하는 시점을 명세에 적습니다.

계정 전환 중 발생한 이벤트에는 발생 당시의 회원 ID를 남깁니다. 뒤늦게 처리할 때 현재 로그인 계정으로 덮어쓰면 다른 사람의 행동이 됩니다. 탈퇴 시에는 OneSignal의 삭제 범위와 함께 송신 대기열·재처리 작업도 정리할 담당을 둡니다. 삭제 후 연동 작업이 사용자를 다시 만드는 경로까지 확인합니다. OneSignal Delete users

IXC-DEMO-01은 가상 B2B 협업 서비스에서 팀 초대를 수락한 사용자의 공동 작업 완료를 안내합니다. 회원은 usr_demo_01, 워크스페이스는 ws_demo_01, 초대는 inv_demo_01입니다. 초대 서버가 수락 저장을 확정한 사건은 invitation_accepted, 작업 서버가 해당 공동 작업의 완료 저장을 확정한 사건은 shared_task_completed입니다. 실계정 이벤트 전송·메시지 수신 시험은 미실시 상태입니다.

예제에서는 사용자당 활성 초대를 하나로 제한합니다. 공동 작업 생성 시 어느 초대에서 시작한 업무인지 서버에 관계를 저장합니다. 두 이벤트의 user_id, workspace_id, invitation_id가 일치해야 같은 캠페인의 시작과 완료로 연결합니다. 다른 조직의 완료를 섞지 않으며 관계가 확인되지 않는 작업은 해당 초대의 완료로 집계하지 않습니다.

현재 멤버십이나 개인화에 쓰는 상태는 사용자 속성으로, 특정 시점의 수락과 완료는 이벤트로 정의합니다. 이름에는 행동의 의미를 고정하고 조직 ID나 캠페인 ID는 properties에 담습니다. OneSignal Custom events는 이벤트를 영구적인 프로필 상태와 구분합니다. 흐름 전체는 고객 여정 설계 워크북과 연결합니다.

내부 명세의 공통 필드는 문자열 user_id·workspace_id·invitation_id, 사건별 UUID인 event_id, UTC 시각 occurred_at·received_at, 정수 schema_version입니다. occurred_at은 업무 확정 시각, received_at은 중계 서버가 받은 시각입니다. 발생 시각을 수신 시각으로 덮어쓰지 않아야 지연과 순서 역전을 확인할 수 있습니다.

수락 이벤트의 작성 예시는 name=invitation_accepted, user_id=usr_demo_01, workspace_id=ws_demo_01, invitation_id=inv_demo_01, campaign_id=IXC-DEMO-01, schema_version=1입니다. event_id는 0a16ce21-7e35-4f9e-a5ac-9a331944ab01, occurred_at은 2026-09-10T01:00:00Z로 둡니다. 같은 수락의 재전송에는 같은 event_id를 유지합니다. 작업 완료는 같은 업무 관계와 새로운 사건 ID·완료 시각을 사용합니다.

OneSignal 요청의 events 배열 안에서 user_id를 external_id, occurred_at을 timestamp, event_id를 idempotency_key에 매핑합니다. name은 이벤트명으로 사용하고 workspace_id·invitation_id·campaign_id·schema_version은 properties에 넣습니다. received_at은 중계 서버의 관측 기록에 보관합니다. 업무 원문이나 초대 토큰은 이 캠페인의 판정 필드에 포함하지 않습니다. Create custom events API

회원이나 초대 ID가 없으면 공용 값으로 채우지 않고 입력을 격리합니다. 같은 event_id가 다시 오면 기존 처리 결과를 조회하고 추가 업무 실행을 막습니다. OneSignal의 동일 idempotency_key 중복 억제는 4시간의 최선 노력 방식이므로 내부 처리 기록을 대신하지 않습니다. HTTP 202에도 개별 errors가 들어올 수 있어 응답 전체를 성공으로 묶지 않습니다. Create custom events API 오류·중복 처리

완료가 수락보다 먼저 도착한 경우의 기대 결과는 완료 상태 유지와 안내 제외입니다. 늦게 온 수락이 상태를 미완료로 되돌려서는 안 됩니다. timestamp를 넣었다는 이유만으로 도착 순서 문제가 해결됐다고 판단하지 않습니다. 원본의 최종 상태, 발생 시각, 수신 시각, 처리 기록을 함께 대조합니다.

다른 조직의 완료는 현재 업무에 영향을 주지 않아야 합니다. 탈퇴 뒤 남은 이벤트는 송신을 막고 정리 결과를 남깁니다. 사용자 연결 실패를 복구한 후에도 현재 완료·동의 상태를 다시 평가합니다. 복구됐다는 이유로 오래된 안내를 즉시 재생하지 않습니다.

이벤트마다 의미, 발행 주체, 필수 값과 타입, 소비하는 여정과 지표, 정상·오류 예제를 작성합니다. 각 시험의 기대 결과와 실제 결과, 로그 위치를 연결합니다. 미실시 시험은 미실시로 남기고 검토자와 다음 확인 작업을 적습니다. 다운로드 PDF와 작성 양식의 언어는 한국어입니다.

필드의 이름·타입·의미가 바뀌면 schema_version과 변경 이력에 반영합니다. 이전·신규 버전이 동시에 들어오는 기간, 영향받는 여정과 측정 쿼리, 적용·복귀 절차를 합의합니다. CRM 캠페인 QA 자료의 입력 사례로 검증한 뒤 미해결 조건을 READY, READY WITH CONDITIONS, HOLD로 판정합니다.

IXC의 고객 데이터 연동 설계는 필요한 이벤트와 속성을 정하고 식별자·이벤트 전송을 구현하거나 개발팀 구현을 검토합니다. 작성한 명세로 데이터 원본과 담당, 오류 처리, 측정 도구의 역할과 인수 시험을 협의합니다. 초기 SDK 준비는 OneSignal 온보딩과 연결합니다.