SDK v1 이벤트 모델 정리: decide/expose/track 분리와 attribution 표준화

[soohyunme]

배경

12기 회고 준실험은 1회성 연동으로 현재 구현을 유지하고, SDK에는 포함하지 않는다.

다만 SDK를 앞으로 반복 실험의 표준 연동 방식으로 쓰려면 현재 이벤트 모델을 정리해야 한다. 지금 SDK/API는 decide(), exposure/impression, click/conversion attribution 경계가 명확하지 않고, event_log와 experiment_event 기준도 나뉘어 있다.

현재 문제

• sdk.decide()가 호출 직후 impression을 자동 전송한다.
• API 호출은 실제 UI 노출이 아니므로, 실제 렌더/viewport 노출 기준과 어긋날 수 있다.
• sdk.track()은 /capture와 /events를 함께 사용해 이벤트 저장 기준이 분산된다.
• 실험 결과 계산은 event_log.exp_exposure를 우선 분모로 쓰지만, 실험 판단 대시보드의 Live Events 계열은 experiment_event.impression/conversion을 본다.
• 노출 1건과 클릭/전환을 안정적으로 연결하는 공통 키가 없다.
• session_id만으로는 같은 세션 안의 여러 노출을 구분하기 어렵다.

목표

SDK v1에서 판단, 실제 노출, 행동 이벤트를 분리하고, 결과 계산과 대시보드가 같은 이벤트 계약을 기준으로 볼 수 있게 한다.

작업 범위

• decide, expose, track 공개 계약 정리
  • decide: 어떤 variant/slot을 줄지 판단
  • expose: 사용자가 실제로 봤을 때 기록
  • track: 클릭/전환 기록
• decide() 직후 자동 impression 전송 제거 또는 옵션화
• tracking_context 표준화
  • experiment_id
  • key 또는 placement_key
  • variant
  • project_id
  • source
  • assignment_id
• correlation key 설계
  • impression_id: 특정 UI 노출 1건 식별
  • session_id: 방문/탭 세션 식별
  • assignment_id: 실험 배정 식별
• SDK 이벤트 저장 endpoint/테이블 기준 정리
  • /capture -> event_log
  • /events -> experiment_event
  • SDK v1 표준 기준 결정
• 결과 계산과 실험 판단 대시보드의 이벤트 기준 정합성 점검
• React helper 검토
  • useExperimentSlot 또는 <ExperimentSlot />
  • viewport 기준 노출
  • 중복 방지
  • impression_id 생성
  • click/conversion attribution 자동 연결

우선순위

• P0: 이벤트 계약 정리
• P0: decide/expose 분리
• P0: tracking_context 표준화
• P1: impression_id/session_id/assignment_id 도입
• P1: 결과 계산과 대시보드 이벤트 기준 통합
• P2: React ExperimentSlot helper
• P2: 문서/QA 가이드

Acceptance Criteria

• decide()만 호출해도 실제 노출 이벤트가 자동 저장되지 않는다. 단, 호환성 때문에 자동 전송을 유지한다면 명시 옵션으로 제어된다.
• sdk.expose(decision) 또는 동등한 API로 실제 노출 이벤트를 보낼 수 있다.
• sdk.track(...) 호출 시 tracking_context 기반 attribution 필드가 자동 포함된다.
• 같은 UI 노출에서 발생한 expose/click/conversion 이벤트를 동일한 impression_id로 연결할 수 있다.
• session_id와 assignment_id의 역할이 타입/문서에 명확히 정의된다.
• 실험 결과 계산과 실험 판단 대시보드가 어떤 이벤트 소스를 기준으로 하는지 정리되어 있다.
• SDK README 또는 연동 가이드에 decide/expose/track 사용 기준이 반영된다.

제외 범위

• 12기 회고 준실험 구현 변경
• LVUP 회고 배너 직접 구현 변경
• 이번 준실험 운영 중 impression_id retrofitting