Universal & Deep Links: 2026 완전 가이드
Source: Dev.to
계획
Universal Links와 App Links는 네 개의 레이어가 올바르게 맞춰질 때만 작동합니다. 이 가이드에서는 각각을 차례대로 살펴보겠습니다:
도메인
iOS와 Android가 URL을 신뢰하도록 AASA와 assetlinks.json을 설정하는 방법.
모바일 앱
iOS 권한(entitlements), Android 매니페스트, 그리고 네이티브 URL 핸들러에 무엇이 들어가야 하는지.
호스팅 또는 프레임워크
Next.js, Firebase, Vercel 같은 플랫폼이 파일을 재작성하거나 리다이렉트하면 Universal Links가 깨질 수 있는 이유.
클라이언트‑사이드 로직
React Native 안에서 URL 경로와 쿼리 파라미터를 매핑해 올바른 화면을 여는 방법.
이 과정을 마치면 각 조각이 어떻게 맞물리는지, 왜 Universal Links가 종종 조용히 실패하는지, 그리고 문제가 발생했을 때 빠르게 디버깅하는 방법을 이해하게 됩니다.
딥링크 기본
구현에 들어가기 전에 다루게 될 두 종류의 딥링크를 이해하는 것이 중요합니다: 커스텀 URL 스킴과 Universal/App Links. 두 방식 모두 앱 내부의 특정 화면을 열지만 동작 방식과 목적이 크게 다릅니다.
커스텀 URL 스킴
커스텀 스킴은 다음과 같은 형태입니다:
myapp://reset-password?token=123간단하고 내부 네비게이션에 유용하지만 심각한 제한이 있습니다:
- 앱이 설치된 경우에만 동작합니다.
- 대체 동작이 없습니다(링크가 아무것도 하지 않음).
- 다른 어떤 앱도 동일한 스킴을 등록할 수 있습니다.
- 일부 앱과 이메일 클라이언트는 이를 완전히 차단합니다.
커스텀 스킴은 특정 인앱 흐름에 여전히 유용하지만, 외부에서 전달되는 경우에는 신뢰할 수 없습니다.
Universal Links (iOS)와 App Links (Android)
현대적인 접근 방식입니다. 두 플랫폼 모두 HTTPS + 도메인 검증 기반의 보안 딥링크로 전환했습니다.
Universal/App Link는 일반적인 링크처럼 보입니다:
https://example.com/reset-password?token=123- 앱이 설치되어 있으면 해당 화면을 엽니다.
- 설치되지 않았으면 웹사이트로 이동합니다.
시스템이 해당 도메인을 “소유”하고 있음을 검증하기 때문에, 이러한 링크는:
- 더 안전함
- 더 예측 가능함
- 이메일, SMS, 브라우저, 대부분의 앱에서 지원됨
- 하이재킹이나 잘못된 앱이 링크를 여는 상황을 방지하도록 설계됨
언제 어떤 것을 사용할까
- Universal/App Links: 앱 외부에서 오는 모든 경우(이메일 인증, 초대, 비밀번호 재설정, 공유 링크, 푸시 알림)
- 커스텀 URL 스킴: 앱 내부에서의 깊은 네비게이션(특히 웹뷰나 하이브리드 화면 간 전환)
Universal & App Links 작동 원리
Universal Links(iOS)와 App Links(Android)가 안정적으로 동작하려면, 사용자가 링크를 탭했을 때 실제로 무슨 일이 일어나는지 이해하는 것이 도움이 됩니다. OS는 단순히 “앱을 열어라”가 아니라, 신뢰성을 판단하기 위해 일련의 검증 과정을 수행합니다. 대부분의 개발자는 이 과정을 보지 못하고, 그래서 Universal Links가 설명 없이 실패하는 경우가 많습니다.
OS 결정 흐름
도메인 검증
Universal/App Links는 전적으로 도메인 검증에 의존합니다. OS가 검증 파일을 가져오지 못하거나 잘못 제공되면, 모바일 코드가 아무리 완벽해도 Universal Links는 앱을 열지 못합니다.
검증이 실패하는 일반적인 이유:
- 리다이렉트 뒤에 있는 검증 파일
- 잘못된 Content‑Type 헤더(
text/html대신application/json) - 호스팅 플랫폼이 라우트를
index.html로 재작성 - 잘못된 도메인(
www.example.com대신example.com)
OS가 검증에 실패하면 그 실패를 캐시하는 경우가 많아, 테스트 중에 앱을 삭제해야 할 때가 있습니다.
앱 설치 여부에 따른 동작
검증이 끝난 뒤 OS는 두 가지 결과 중 하나를 선택합니다:
앱이 있으면 링크가 앱을 열고, 없으면 웹사이트를 엽니다. 이는 커스텀 URL 스킴에 비해 큰 장점이며, 사용자는 언제나 의미 있는 위치에 도달합니다.
실제 시나리오
Universal/App Links가 가장 많이 사용되는 경우:
- 이메일 인증
- 비밀번호 재설정
- 초대 흐름
- 공유 콘텐츠
- 앱으로 딥링크되는 푸시 알림
- 웹뷰 → 앱 전환
이 모든 흐름은 동일한 OS 결정 로직에 의존하므로, 도메인 하나만 잘못 설정돼도 한 번에 모두 깨질 수 있습니다.
웹 설정
Universal Links와 App Links는 도메인이 올바르게 구성돼야만 작동합니다. 이는 전체 설정 중 가장 민감한 부분이며, 가장 자주 깨지는 지점입니다. iOS나 Android가 정확한 형식과 헤더를 가진 검증 파일을 읽지 못하면, 다른 모든 것이 완벽해도 앱은 열리지 않습니다.
검증 파일
두 플랫폼 모두 매우 특정한 경로에 파일이 존재하기를 기대합니다.
iOS – apple-app-site-association
/.well-known/apple-app-site-association- raw JSON이어야 함(
.json확장자 없이) Content-Type: application/json으로 제공되어야 함- HTTP 200 응답이어야 함
Android – assetlinks.json
/.well-known/assetlinks.json- 유효한 JSON 배열이어야 함
- 패키지 이름과 SHA‑256 인증서 지문을 포함해야 함
Content-Type: application/json과 HTTP 200 응답이어야 함
이 파일들은 OS에 “이 도메인은 이 앱에 속한다. 직접 링크를 열어도 안전하다”는 신호를 보냅니다. OS가 파일을 로드하거나 파싱하지 못하면 Universal/App Links는 조용히 실패합니다.
파일 호스팅 요구사항
OS가 기대하는 조건은 다음과 같습니다:
- HTTPS 전용(HTTP 금지)
- 리다이렉트 없음(301·302 하나라도 검증을 깨뜨림)
- 파일을 가져오는 데 인증이나 쿠키 필요 없음
- 정확한 경로:
/.well-known/는 그대로 사용 - 올바른 Content‑Type 헤더(
application/json) - 200 상태 코드 응답
index.html폴백 없음(Next.js 같은 프레임워크에서 흔히 발생)
호스팅 플랫폼이 URL을 재작성하거나 HTML 응답을 강제하면 OS는 도메인을 받아들이지 않습니다.
서버 제약 및 체크리스트
도메인 설정이 올바른지 빠르게 확인할 수 있는 체크리스트:
- 두 파일 모두
/.well-known/에 위치 - HTTPS와 유효한 TLS 인증서 사용
- 리다이렉트 없이 직접 200 응답
Content-Type: application/json헤더 정확히 설정- 파일 내용이 유효한 JSON( iOS는 raw, Android는 배열)
- Android 파일에 올바른 패키지명과 SHA‑256 지문 포함
- 인증, 쿠키, 기타 요청 수정 필요 없음
index.html이나 다른 재작성 규칙이 없음
이 체크리스트를 만족하면 OS가 도메인을 검증할 수 있게 되고, Universal/App Links가 양 플랫폼에서 안정적으로 동작합니다.