Files

11 KiB

이벤트 상세 딥링크·AppsFlyer 연동 PRD

문서 정보

  • 상태: Phase1·Phase2 구현·로컬 검증 완료 (실서버 검증 제외)
  • 작성일: 2026-10-29
  • 대상: 이벤트 상세 직접 URI·푸시·AppsFlyer UDL 진입
  • 결정권자: 사용자
  • 관련 계획: plan-task.md
  • 이번 작업은 이벤트 상세 API 연동과 별도 작업이다. 기존 API/화면은 재사용하며 이전 작업 문서는 수정하지 않는다.

1. 목표

직접 URI, 기존 FCM/알림함/Notifly의 클릭 URL 및 AppsFlyer direct/deferred 콜백에서 양수 Long 이벤트 ID로 동일한 v2.event.EventDetailActivity를 연다. 비로그인도 이벤트 상세에 진입하고, 늦은 콜백·앱 준비 전 전달·동일 진입 중복·Activity 재생성에 대응한다.

2. 현재 문제

  • DeepLinkActivity와 MainV2Activity의 라우터에 event-detail 분기가 없다.
  • FCM notification+data의 런처 진입은 raw extras를 MainV2에 전달하지만 MainV2는 deep_link만 URL로 읽고 deepLink를 정규화하지 않는다.
  • MainV2의 공통 라우팅 앞 로그인 검사로 공개 이벤트도 차단된다.
  • AppsFlyer 콜백은 마케팅 값을 저장하지만 MainV2에 저장 목적지를 소비하는 연결이 없다.
  • SDK는 init → start → subscribeForDeepLink 순서이며 공식 UDL 지침은 listener를 start 전에 등록하도록 한다.

3. 확정 입력 계약

입력 계약
release 직접 URI voiceon://event-detail/{eventId}
debug 직접 URI voiceon-test://event-detail/{eventId}
FCM data deep_link에 전체 URI; 기존 deepLink 별칭도 수용
알림함 기존 deepLink 필드에 같은 URI
Notifly 캠페인 클릭 URL에 같은 URI; SDK 1.12.0은 ACTION_VIEW로 전달
OneLink URL 현재 빌드의 APPLINK_HOST에 대한 HTTPS URL, deep_link_value=event-detail, deep_link_sub5={eventId}
AppsFlyer UDL 콜백의 deep_link_value=event-detail, deep_link_sub5={eventId}

ID는 하나의 ASCII 십진수 문자열을 양수 Long으로 파싱한다. 1..9223372036854775807을 보존하며 0/음수/비숫자/공백/overflow/추가 경로를 거부한다. direct path ID는 query의 다른 ID로 대체하지 않는다. 잘못된 이벤트 입력을 다른 도메인 라우팅으로 바꾸지 않는다. 서로 다른 환경 스킴이나 임의 외부 HTTPS host를 이벤트 링크로 수용하지 않는다.

EventDetailActivity.newIntent(context, eventId: Long)만 호출하고 Parcelable 데이터나 새 상세 API는 만들지 않는다. 상세 조회의 loading/성공/조회 불가/오류는 기존 화면 책임이다.

4. 기능 요구사항

ID 상태 요구사항·수용 기준
EDL-001 확정 허용 URI/OneLink/UDL의 양수 Long을 동일한 상세 진입점에 연결한다. 누락·무효 입력은 상세를 열지 않는다.
EDL-002 확정 foreground와 Splash를 거치는 cold/background, MainV2 새 Intent에서 동일 이벤트를 처리한다. FCM 두 URL key를 이벤트 경계에서 정규화한다.
EDL-003 확정 이벤트만 비로그인 진입 가능하다. 기존 다른 도메인 로그인/성인 가드, 자체 FCM 수신의 토큰 조건은 변경하지 않는다.
EDL-004 확정 AppsFlyer listener를 start 전에 등록하고 기존 마케팅 PID/UTM 저장·Firebase 추적을 유지한다.
EDL-005 확정 Activity 준비 전 또는 준비 후 늦게 도착한 UDL을 처리한다. 백그라운드에서 강제로 Activity를 띄우거나 종료된 Activity 참조를 유지하지 않는다.
EDL-006 확정 같은 이벤트 OneLink의 URI+UDL은 UDL만 이동을 소유하여 이중 실행하지 않는다. Intent 재생성·handoff는 단회 처리한다. 새로운 명시적 동일 이벤트 진입과 새 UDL 전달은 허용하며 영구 eventId 차단/임의 TTL은 사용하지 않는다.
EDL-007 확정 라이브룸의 기존 이동 확인을 거친다. 오디오 알림·gift·DM·콘텐츠·채널 등의 기존 라우팅 우선순위와 정책은 유지한다.
EDL-008 확정 기존 Manifest 공개 라우터를 사용하고 상세 Activity의 exported=false를 유지한다. 필요한 최소 경계만 변경한다.
EDL-009 확정 이벤트도 기존 Bundle 정규화·목적지 dispatcher에서 실행한다. handleEventEntry/handleEventDeepLink의 별도 선행 실행은 제거하고, AppsFlyer helper는 입력 대기·전달만 담당한다.

5. 포함·제외 및 승인

  • 신규 helper·상태·테스트는 kr.co.vividnext.sodalive.v2.event 하위에 작성한다.
  • 사용자 승인: main/DeepLinkActivity.kt, app/SodaLiveApp.kt를 이벤트 연결 및 AppsFlyer 초기화 순서 보정에 한해 최소 수정한다.
  • MainV2의 이벤트 연결, 필요하면 v2 이벤트 상세의 lifecycle 연결은 이번 범위다. 이벤트 API·표시 UI는 바꾸지 않는다.
  • Manifest/FCM 서비스/Splash/알림함/LiveRoomActivity/공통 인증 저장소/기존 OneLink 공유 함수의 전면 수정은 하지 않는다.
  • AppsFlyer SDK 업그레이드·대시보드 변경·신규 SDK/의존성·다른 도메인의 UDL 복구·기기 UI/계측 테스트는 제외한다.
  • 사용자 지시대로 현재 main 브랜치에 직접 작업한다. worktree/새 브랜치/커밋/푸시는 만들지 않는다.
  • 사용자 지시대로 실서버 연결 테스트와 실제 푸시 발송은 하지 않는다. 로컬 fake/fixture 및 Robolectric 라우팅 테스트만 사용한다.

6. 검증 시나리오

  1. 정상: 직접 URI, 두 FCM URL key, OneLink query, UDL direct/deferred의 유효 ID가 기존 상세를 연다. release/debug 설정을 각각 지킨다.
  2. 경계: 잘못된 ID·외부 scheme/host·경로/query 충돌·중복 alias를 거부하고 Int 범위 초과/Long.MAX_VALUE를 보존한다.
  3. 비동기: 콜백 선도착·후도착, 준비 전 여러 입력, background→foreground, Activity 재생성/종료, URI/UDL 양쪽 순서, 사용자의 같은 ID 재클릭을 검증한다.
  4. 인접 회귀: 비로그인 이벤트와 비이벤트 가드, 라이브룸 확인·취소, 오디오 알림·gift 단회 소비·기존 푸시 extras 및 마케팅 저장을 확인한다.

7. 외부 의존과 검증 한계

  • AppsFlyer 대시보드의 OneLink template, SHA-256, fallback, 실제 캠페인 설정은 로컬 코드로 입증하지 않는다.
  • SDK가 두 콜백에 동일한 클릭 식별자를 보장하지 않는 경우 중복 방지의 정확한 소유 범위와 한계를 구현 계획에 명시한다. 추측한 provider field를 도입하지 않는다.
  • 키·토큰·서명 정보·SDK payload 전체를 로그나 문서에 기록하지 않는다.

8. 전달 소유권과 생명주기

  • 커스텀 이벤트 URI는 Intent가 소유한다. 이벤트 OneLink URI는 앱 bootstrap만 수행하고 상세 이동은 유효한 UDL 콜백이 소유한다. SDK 실패 시 URL만으로 상세 이동하는 자동 fallback은 추가하지 않는다.
  • Application 소유 event helper는 main thread에서 process-local FIFO를 관리하고 resumed Activity를 weak reference로만 참조한다. Splash·DeepLink trampoline 및 초기 라우팅이 완료되지 않은 Main에서는 대기한다.
  • 콜백 도착과 Activity resume 모두 대기 전달을 확인한다. 현재 Activity가 종료/일시정지됐으면 실행하지 않는다. background에서 강제 startActivity하지 않는다.
  • UDL은 현재 resumed Activity를 통해 명시적 DeepLinkActivity Intent로 넘겨 기존 라이브룸 확인을 재사용한다. 전달 후 큐에서 제거하며 사용자가 확인을 취소해도 재전달하지 않는다.
  • 각 Intent 진입의 로컬 token과 전달/소비 상태를 handoff Bundle 및 savedInstanceState에 보존한다. 이는 동일 entry 재생성 방지용이지 provider 클릭 identity가 아니다.
  • 새로운 SDK 콜백은 새로운 전달로 취급한다. provider가 같은 클릭을 중복 callback으로 전달한 경우와 실제 동일 ID 재클릭을 입력 필드만으로 구분할 수 없으며, 이 경우 새 클릭 보존을 우선한다. 커스텀 URI가 별도 event UDL echo까지 일으키는 비표준 발송 조합의 완전 중복 제거는 보장하지 않는다.
  • 프로세스 종료 후 별도 영구 navigation queue는 복구하지 않는다. 복원된 launch Intent/saved state 또는 새 SDK callback을 사용한다. 마케팅 preference를 navigation queue로 읽지 않는다.

Decision Log

날짜 ID 결정·근거
2026-10-29 EDEC-001 별도 작업으로 PRD/계획 생성. 기존 이벤트 API 작업과 구분한다.
2026-10-29 EDEC-002 사용자 요청으로 AppsFlyer도 동일 이벤트 상세에 연결한다.
2026-10-29 EDEC-003 사용자 승인으로 DeepLinkActivity/SodaLiveApp의 최소 연결·등록 순서 변경 허용.
2026-10-29 EDEC-004 단일 event-detail 계약, guest 이벤트만 허용, 공통 다른 라우팅·추적은 보존한다.
2026-10-29 EDEC-005 Oracle 설계 검토에 따라 custom URI/OneLink UDL 소유권 분리. 제공되지 않은 click ID나 시간 기반 중복 차단을 만들지 않는다. OneLink는 SDK 전달 성공에 의존한다.
2026-10-29 EDEC-006 사용자 요청으로 기존 공통 라우팅 확장 + AppsFlyer 입력 어댑터 방향으로 후속 리팩터링한다. Phase1의 별도 이벤트 실행 분기는 공통 dispatcher 내부 이벤트 목적지로 대체한다. EDEC-005 소유권·비동기 전달·외부 입력 계약은 유지한다.

완료 기준

  • EDL-001~008의 로컬 테스트 및 회귀 통과
  • 전체 unit suite·main/test ktlint·debug 빌드 검증 및 한계 기록
  • 최종 리뷰 승인: phase1-event-deeplink-appsflyer-review.md
  • 소유 임시 자원 정리

Phase2 추가 완료 기준

  • DeepLinkActivity.routeForegroundDeepLink와 MainV2Activity.executeBundleRoute에서 이벤트 목적지를 처리하고, 별도 이벤트 실행 우회 함수가 없다.
  • 이벤트 ID/URL은 입력 정규화에서 검증하며 raw event_id·외부 URL·SDK 소유 입력이 실행 가능한 이벤트로 승격되지 않는다.
  • 비로그인 정책·단회 소비·새 same-ID 클릭·late UDL·기존 도메인 회귀를 보존한다.
  • 전체 로컬 검증·Phase2 리뷰·이번 단계 임시 자원 정리 완료.

Task2.1 로컬 증거: 기존156개 + 정규화/공통 dispatcher 신규14개 = 170개 통과, main/test ktlint 통과. 정확한 interface·RED/GREEN·실행 명령·임시 로그 위치는 계획 Task2.1 검증에 기록했다. 전체 suite/build/Phase2 리뷰와 최종 자원 정리는 parent Task2.2에서 수행한다.

Task2.2 최종 증거: 전체1736개 통과·lint 위반0·debug 빌드 성공. Phase2 코드 리뷰 APPROVE. 실서버와 기기 UI는 제외했으며 중간 인증 테스트 실패/worker 중단 기록과 검증 한계는 계획·리뷰에 보존한다.