7.9 KiB
이벤트 상세 딥링크 및 OneLink 연동 PRD
문서 정보
| 항목 | 내용 |
|---|---|
| 문서 상태 | 클라이언트 구현·로컬 검증 완료, 실제 단축 URL 성공 검증은 비차단 후속 항목 |
| 작성일 / 최종 수정일 | 2026-10-29 |
| 대상 제품 | SodaLive iOS 이벤트 상세 진입 |
| 작성자·결정권자 | 사용자 승인 범위, 실행자는 게이트 이후 구현 |
| 관련 API Contract | api-contract.md |
| 관련 구현 계획 | plan-task.md |
| 관련 review | 최종 구현 리뷰, 실제 SDK 검증 |
1. Overview와 문제
OS/SDK가 전달하는 이벤트 URI·OneLink와 앱 내부 알림 입력을 기존 AppStep.eventDetail(eventId:)로 연결한다. 비로그인 및 cold start에서도 기존 pending 경로를 재사용한다. SDK 6.17.5에서 performOnAppAttribution(with:)가 UDL 활성 시 didResolveDeepLink로 긴 URL의 이벤트 값을 반환함을 실제로 확인했고 이를 구현에 사용한다. 정상 단축 URL의 서버 해석은 사용자 결정에 따라 비차단 후속 검증으로 남긴다.
2. 목표와 성공 기준
- 커스텀 URL, OneLink, push, Notifly URL, 알림 목록 진입을 한 이벤트 ID 처리 경로로 연결한다.
- cold start 및 로그인 전에는 기존 공통 pending queue를 사용하고, 잘못된 ID가 현재 화면이나 pending 목적지를 변경하지 않게 한다.
- 동일 pending/current/delivery의 중복만 억제한다. 이후 사용자가 다시 탭한 동일 링크는 새 탐색으로 허용한다.
- 실제 SDK 공존 증거와 DEC-004의 사용자 후속 결정으로 구현 진입 조건을 충족했다. 단축 URL의 실제 서버 성공을 로컬 테스트 결과와 혼동하지 않는다.
3. Non-Goals
새 이벤트 화면/API, 새 이벤트 ID 라우트 별칭, pushEventId, 전역 router 재작성, SDK 업그레이드, share button, OneLink 생성·AppsFlyer/AASA/실제 push 전달 설정은 제외한다. 실백엔드 검증과 실제 공급자 연동 검증도 이 작업에서 하지 않는다.
4. 라우팅 및 동작 요구사항
| ID | 상태 | 요구사항 | 수용 기준 | Contract / Goal |
|---|---|---|---|---|
| LINK-001 | 확정 | 프로덕션 URI는 voiceon://event-detail/{id}, 개발 URI는 voiceon-test://event-detail/{id}만 허용한다. |
이벤트 alias 없음. ID는 양수 signed 64-bit 정수. | Contract §1, P2-T1 |
| LINK-002 | 확정 | OneLink는 정확한 HTTPS host voiceon.onelink.me의 short/long URL이며 deep_link_value=event-detail, deep_link_sub5={id}를 사용한다. |
deep_link_sub1~deep_link_sub4 기존 마케팅 값은 건드리지 않는다. |
Contract §2, P2-T1 |
| LINK-003 | 확정 | 표준 push deep_link, Notifly url, 알림 목록 deepLink는 커스텀 URI 또는 HTTPS OneLink를 받는다. |
shortlink는 SDK가 해석해야 한다. query만 직접 읽어 shortlink를 우회하지 않는다. | Contract §3, P2-T2 |
| LINK-004 | 확정 | SDK push 경로는 addPushNotificationDeepLinkPath([deep_link])를 SDK 시작 전에 등록하고 실제 userInfo로 handlePushNotification을 호출한다. |
HTTPS OneLink만 SDK push handler로 전달한다. Notifly marker와 URL이 함께 있으면 소유자 하나만 라우팅한다. 같은 payload를 deep_link나 AppsFlyer push로 중복 전달하지 않는다. |
Contract §3, P2-T2 |
| LINK-005 | 확정 | 목적지는 기존 AppStep.eventDetail(eventId:)다. |
기존 상세 UI/API 계약과 route 이름은 유지한다. 공통 pending queue를 사용하며 cold start 및 로그인 전에도 보존한다. | Contract §4, P2-T1 |
| LINK-006 | 확정 | 비양수, 숫자 아님, overflow ID는 무시한다. | 잘못된 입력은 기존 current 또는 pending 목적지를 바꾸지 않는다. 같은 pending/current/delivery만 억제하며 이후 새 사용자 탭은 허용한다. | Contract §1, P2-T1 |
| LINK-007 | 확정 | 기존 live 종료 확인을 보존한다. | 확인 취소 시 탐색하지 않는다. 기존 GCD와 route는 유지한다. | Contract §4, P2-T1 |
5. 초기 SDK 게이트 기록(후속 DEC-004로 구현 차단 해제)
P1-GATE가P2전체의 선행조건이다. 설치된 SDK 6.17.5의 공개 계약 조사와 실행 격리 사전 점검을 마쳤으나 gate를 통과하지 못했다. 제품 코드는 수정하지 않는다.performOnAppAttribution(with:)는 URL-only legacy resolver이며 공개 계약이 존재한다. 다만 UDL delegate가 동시에 설정된 상태에서의 콜백 선택을 확인하지 못했다. 합성 activity나 가짜 SDK callback의 성공만으로 실제 SDK 동작을 입증한 것으로 취급하지 않는다.- gate 실패 시 지원 API를 추측하거나 구현하지 않는다. 공급자 지원 확인 또는 별도 승인된 실제 SDK 테스트를 요청하고 정지한다.
- 기존 SDK 초기화, GCD 처리, 라우트 및 pending queue를 존중한다. 새 alias·의존성·프로젝트 설정 변경을 만들지 않는다.
6. 추적 및 결정
| 날짜 | ID | 상태 | 결정 | 영향 |
|---|---|---|---|---|
| 2026-10-29 | DEC-001 | 확정 | 사용자 승인 범위는 딥링크/OneLink이며 SDK feasibility gate 통과 전 구현 금지 | P1-GATE, P2 |
| 2026-10-29 | DEC-002 | 확정 | 기존 AppStep.eventDetail(eventId:)와 공통 queue 재사용 |
LINK-005 |
| 2026-10-29 | DEC-003 | 확정 | 현재 branch에서 작업, 승인 없는 commit 및 worktree 생성 없음 | 실행 범위 |
7. 제외 범위
기존 완료 문서 이벤트 상세 API 연동은 별개이며 수정하지 않는다. 실제 AppsFlyer/Notifly/AASA/push 전달과 backend 검증은 별도 승인 대상이다.
추가 승인 - 2026-10-29
사용자가 AppsFlyer 테스트 OneLink의 실제 SDK 해석에 한해 검증을 허용했다. 기존 UDL과 manual URL resolver의 공존 동작 확인만 수행한다. 이벤트 API/앱 서버 호출, 푸시 발송, 운영 앱 실행, 공급자 콘솔 설정 변경은 계속 제외한다. 제품 구현 gate는 검증 결과 전까지 유지한다.
실제 SDK 검증 결과 - 2026-10-29
긴 HTTPS OneLink는 현재 SDK 6.17.5에서 UDL delegate가 설정된 상태의 수동 resolver 호출 후 didResolveDeepLink(found)로 event-detail/123을 반환했다. legacy-only 대조군도 확인해 콜백 선택의 이전 불확실성을 해소했다. 공식 단축 URL 예시는 해석에 실패했으며 정상 short fixture의 양성 검증은 남았다. 당시 gate 유지 판정과 제한은 실행 기록에 보존한다.
사용자 후속 결정: 단축 URL 없이 구현 진행 - 2026-10-29
- 사용자: "단축 URL을 만들어 둔 것이 없다. 요구사항대로 진행한다."
- DEC-004: 정상 단축 URL의 실연결 양성 검증을 구현 차단 조건에서 제외한다. 이미 실제로 확인한
performOnAppAttribution(with:)→ UDL 경로를 사용해 긴/단축 HTTPS OneLink를 SDK에 전달한다. 실연결 성공을 추정하거나 단축 링크를 직접 생성하지 않는다. - 로컬 SDK 경계 대역으로 short/long 전달, UDL 성공/실패, 이벤트 ID, 중복·cold start·live 취소 및 push owner를 검증한다. SDK 자체 short 서버 해석은 후속 검증으로 명시한다. 추가 인터뷰나 fixture 요청 없이 구현·빌드·리뷰를 진행한다.
최종 클라이언트 검증 - 2026-10-29
이벤트 딥링크 345 assertion, 기존 deep-link 279 assertion 및 전체 로컬 회귀 15개가 통과했다. SodaLive/SodaLive-dev Debug 시뮬레이터 빌드도 통과했고, 단일 리뷰의 비동기 경합 지적을 RED/GREEN으로 수정한 뒤 delta APPROVE를 받았다. 실제 정상 short 링크·실제 푸시/Notifly 전달·앱 서버 및 전체 기기 UI 동작은 이번 완료 주장에 포함하지 않는다.