docs(event): 딥링크 계약과 검증 기록을 남긴다

2026-10-29 15:44:38 +09:00
parent c78f7417ab
commit e7799449c6
3 changed files with 295 additions and 0 deletions
@@ -0,0 +1,39 @@
+# 이벤트 상세 딥링크 연동 계약
+
+## 1. URI와 ID
+- 프로덕션: `voiceon://event-detail/{id}`
+- 개발: `voiceon-test://event-detail/{id}`
+- `event` 같은 alias는 허용하지 않는다. `{id}`는 양수 signed 64-bit 정수이며 숫자 아님, 0, 음수, overflow는 거부한다.
+- 유효한 값은 기존 `AppStep.eventDetail(eventId:)`에 전달한다. 별도 화면/API/라우트는 없다.
+
+## 2. OneLink
+- HTTPS hostname은 정확히 `voiceon.onelink.me`여야 한다. short URL과 long URL 모두 AppsFlyer SDK URL 해석 대상이다.
+- 해석된 이벤트 값은 `deep_link_value=event-detail`, `deep_link_sub5={id}`다.
+- `deep_link_sub1`~`deep_link_sub4`는 기존 마케팅 의미를 보존한다.
+- shortlink는 SDK가 해석한 결과만 소비한다. shortlink query를 직접 읽는 우회는 금지한다.
+- 실제 SDK 6.17.5에서 `performOnAppAttribution(with:)`를 호출하면 UDL 활성 시 `didResolveDeepLink`로 긴 URL의 이벤트 값이 반환됨을 확인했다. 앱 내 HTTPS URL은 이 경로를 사용한다. 실제 정상 short 서버 해석은 미검증이며 사용자 후속 지시에 따라 구현 차단 조건에서는 제외한다.
+
+## 3. 인입 소유권
+| 진입 | 입력 계약 | 처리 |
+|---|---|---|
+| 커스텀 URL | §1의 앱별 URI | 공통 deep link queue로 전달 |
+| 일반 push `deep_link` | §1 URI 또는 §2 HTTPS OneLink | custom URI는 앱 경로, HTTPS OneLink는 SDK 처리 |
+| Notifly `url` | §1 URI 또는 §2 HTTPS OneLink | 기존 Notifly 경로에서 한 번 전달 |
+| 알림 목록 `deepLink` | §1 URI 또는 §2 HTTPS OneLink | 검증 후 필요한 최소 SDK bridge 연결, 공통 pending 재사용 |
+| SDK push | HTTPS OneLink만 | SDK 시작 전 `addPushNotificationDeepLinkPath([deep_link])`; 실제 userInfo로 `handlePushNotification` |
+
+Notifly marker와 URL이 같이 있는 payload는 단일 소유자가 처리한다. 같은 payload를 `deep_link` 및 AppsFlyer push 경로로 중복 라우팅하지 않는다. in-app 알림에서 fake push payload를 만들지 않는다.
+
+## 4. 상태와 무효 입력
+- cold start 및 로그인 전 목적지는 기존 공통 pending queue에 보관한다.
+- invalid ID는 current route와 pending route 어느 것도 바꾸지 않는다.
+- 동일 pending/current/delivery의 중복은 억제한다. delivery 이후 사용자가 다시 탭한 동일 링크는 새 요청으로 취급한다.
+- 기존 live leave confirmation을 재사용한다. 취소는 route 변경 없이 끝난다.
+- 기존 GCD 및 라우팅 전달 규칙을 유지한다.
+
+## 5. SDK feasibility 판정 이력
+`P1-GATE` BLOCKED. SDK 6.17.5의 legacy URL-only resolver는 확인했지만 기존 UDL과 공존할 때의 콜백을 입증하지 못했다. 실제 iOS SDK 실행에 대한 fail-closed 네트워크 격리도 확보하지 못해 SDK를 실행하지 않았다. 공급자 지원 확인 또는 별도 승인된 실제 SDK 테스트로 미결 사항을 해결하기 전에는 제품 구현을 진행하지 않는다.
+
+후속 판정: 제한 승인된 실제 SDK 실행에서 긴 URL의 `performOnAppAttribution(with:)`는 UDL이 설정돼 있으면 `didResolveDeepLink`로 event-detail/123을 반환함을 확인했다. 단축 링크의 실패 callback도 관찰했으나 정상 단축 fixture의 성공 해석은 미입증이다. 현재 남은 gate 조건은 해당 양성 증거이며, 이를 확보하기 전 전체 계약 구현 완료를 주장하지 않는다.
+
+최종 사용자 결정(2026-10-29): 단축 URL이 없는 상태로 요구사항 구현을 진행한다. 위 구현 차단 조건은 해제하고 실제 단축 URL 서버 성공 검증만 미실행 후속 항목으로 남긴다. 입력 short/long URL 모두 SDK에 위임하며 앱이 임의 query 해석으로 대체하지 않는다.