앱 MVP Android App Links: 선언·도메인 검증·사용자 선택을 나누는 5가지 기준

앱 MVP Android App Links: 선언·도메인 검증·사용자 선택을 나누는 5가지 기준

먼저 답하기: App Links는 링크를 선언했다고 끝나는 기능이 아니라, 웹 도메인과 앱의 연결을 검증하고 실제 기기에서 확인해야 하는 경로입니다

Android MVP에서 웹의 상품·초대·콘텐츠 URL을 앱 화면으로 연결하려 할 때, 매니페스트에 URL을 넣는 것만으로는 충분하지 않습니다. Android의 일반 딥링크는 intent를 통해 앱이 URL을 처리하도록 등록할 수 있지만, 여러 앱이 처리할 수 있으면 시스템 선택 화면이 나올 수 있습니다(C001). 반면 Android App Links는 내가 소유한 웹사이트와 앱의 신뢰 관계를 검증해, 성공한 경우 해당 웹 링크를 앱으로 바로 보낼 수 있는 기능입니다(C002).

따라서 MVP의 완료 기준은 “코드를 넣었다”가 아니라 다음 다섯 상태를 따로 확인하는 데 있습니다. 어떤 URL을 앱이 맡을지, 매니페스트가 검증 가능한 범위를 선언했는지, 웹 서버의 assetlinks.json이 실제로 맞는지, 기기가 검증 상태를 어떻게 기록했는지, 그리고 검증이 안 됐을 때 웹·선택 화면의 폴백이 사용자 여정에 맞는지입니다. 이 글은 설치·전환·검증 성공을 보장하지 않습니다. 각각을 혼동하지 않기 위한 실무 기준입니다.

기준 1: 일반 딥링크와 App Links가 해결하는 문제를 먼저 나눕니다

일반 딥링크는 custom URI나 웹 URL을 intent filter에 등록해 앱으로 보낼 수 있는 Android의 기본 기능입니다(C001). 다만 같은 링크를 처리할 수 있는 앱이 있으면 사용자는 어떤 앱으로 열지 선택할 수 있습니다. 그래서 “앱으로 열렸는가” 한 번의 관찰만으로 모든 기기에서 동일한 경로가 열린다고 기록하면 안 됩니다.

App Links는 웹의 HTTP 또는 HTTPS URL을 앱과 연관된 것으로 Android가 검증하는 방식입니다(C002). 공식 문서가 웹사이트 딥링크에는 App Links를 권하는 이유도, 검증된 URL은 사용자에게 앱 선택을 다시 요구하지 않고 해당 콘텐츠를 열 수 있기 때문입니다(C003). 여기서 핵심은 앱 화면의 존재가 아니라 **웹 도메인 소유와 연결된 URL의 범위**입니다.

MVP에서는 한 번에 모든 URL을 넣기보다, 사용자가 실제로 다시 방문할 이유가 분명한 한 경로부터 적습니다. 예를 들어 초대 수락 URL이라면 초대 토큰 처리, 로그인 전후, 만료·잘못된 링크, 웹에서 계속 보기 중 무엇이 앱 링크의 책임인지 먼저 정합니다. 캠페인 URL 전체나 관리 페이지를 일률적으로 앱으로 보내는 것은 경로의 의도와 다른 결과를 만들 수 있습니다.

우리 앱 MVP의 링크 진입 경로와 검수 기준 정리하기

기준 2: 매니페스트의 URL 범위와 검증 신호를 따로 확인합니다

공식 설정 절차는 앱 매니페스트에 웹사이트 도메인 또는 URL을 지정하는 intent filter를 추가하고, android:autoVerify="true"로 시스템에 검증 시도를 알린 뒤 웹사이트 연관 정보를 선언하는 순서입니다(C004). 검증 가능한 filter에는 http와 https scheme, 그리고 확인할 host가 필요합니다(C005). 한 줄을 복사해 넣는 행위가 아니라, 우리가 실제로 소유·운영하는 도메인만 정확히 적는 작업입니다.

한 filter 안의 여러 <data> 요소는 가능한 조합으로 병합될 수 있습니다. 그래서 특정 scheme과 host를 한 쌍으로 제한하려는 경우에는 별도 filter가 필요할 수 있습니다(C006). 이 부분을 놓치면 의도하지 않은 URL 조합을 받거나, 반대로 검증 대상이 아닌 호스트를 넓게 선언할 수 있습니다. 코드 리뷰에서는 “URL 예시가 열리는가”뿐 아니라 각 scheme·host·path가 어떤 의도로 존재하는지 표로 대조하세요.

Android 12 이상은 여러 host 중 하나가 검증돼도 그 host의 기본 처리자가 될 수 있지만, Android 11 이하는 선언한 모든 host에 일치하는 Digital Asset Links 파일이 있어야 검증됩니다(C007). 따라서 지원 OS가 섞인 MVP라면 하나의 성공 화면으로 호환성을 단정하지 말고 OS 버전, host, 링크 경로를 각각 기록합니다.

기준 3: `assetlinks.json`은 서버 측 증거로 관리합니다

Android는 intent filter에서 찾은 각 고유 hostname에 대해 https://호스트/.well-known/assetlinks.json을 조회합니다(C008). 이는 앱 패키지와 서명 관계를 웹 도메인이 공개적으로 연결하는 지점이므로, 앱 빌드 산출물과 서버 배포 기록을 같은 완료 상태로 섞으면 안 됩니다. 앱이 준비됐더라도 잘못된 host, 오래된 파일, 접근할 수 없는 파일은 별도 원인입니다.

서브도메인은 서로 다른 host로 취급됩니다. 예를 들어 www와 mobile을 각각 선언했다면 각 도메인에서 유효한 파일을 제공해야 합니다(C009). wildcard를 쓸 때도 문서가 안내한 게시 위치와 실제 host 범위를 확인해야 합니다. 편의상 모든 서브도메인을 선언하는 방식은 운영하지 않는 호스트까지 검증 대상으로 만들 수 있으므로, MVP 단계에서는 필요한 host와 경로만 명확히 두는 편이 복구 범위를 작게 만듭니다.

Android 15 이상에는 서버의 동적 규칙으로 URL 매칭을 세밀하게 조정하는 기능이 있지만, 그 규칙은 앱 매니페스트에 선언한 범위를 넓힐 수는 없습니다(C010). 또한 Android 14 이하는 동적 path 규칙을 동일하게 적용하지 않습니다(C011). “서버에서 바꿨으니 구버전도 즉시 바뀐다”는 표현 대신, OS별로 무엇이 정적 선언을 따르고 무엇이 서버 규칙을 보는지 분리해 두세요.

관련 글 앱 MVP Android Activity Result API: 등록·실행·복원을 나누는 5가지 기준은 앱 안에서 결과를 받는 생명주기를 다룹니다. 이번 글은 웹 URL이 앱 진입점으로 인정되는 도메인 검증 경계를 설명합니다.

기준 4: 실기기 검증은 ‘명령 실행’과 ‘상태 판독’을 분리합니다

autoVerify가 있는 filter가 하나 이상이면 Android 6 이상 기기에 앱을 설치할 때 시스템이 관련 host 검증을 시도합니다(C012). Android 12 이상에서는 설치된 앱의 도메인 검증을 수동으로 다시 요청해 테스트할 수도 있습니다(C013). 그러나 요청 명령을 실행했다는 사실은 완료 결과가 아닙니다. 공식 문서도 비동기 검증이 끝날 시간을 둔 뒤 상태를 확인하라고 안내합니다(C014).

검수 기록에는 package name, 기기 OS, 테스트한 URL, assetlinks.json 조회 가능 여부, 도메인별 상태, 실제 링크 탭 결과를 각각 남깁니다. 상태가 verified면 선언한 앱이 해당 도메인에서 검증됐다는 뜻이고, none은 아직 결과가 기록되지 않았을 수 있어 잠시 뒤 다시 살펴봐야 합니다(C015). 오류 코드나 legacy failure가 나오면 그 자체를 “앱 버그”로 단정하지 말고 네트워크, host 파일, OS별 규칙, 사용자 설정을 차례로 분리합니다.

테스트에서 한 URL이 앱을 열어도, 그 화면의 로그인·권한·만료 링크 처리까지 성공했다는 뜻은 아닙니다. 따라서 링크 처리 성공, 도착 화면 렌더링, 필요한 인증, 원래 의도한 객체를 찾았는지를 독립된 QA 항목으로 둡니다. 이는 링크 클릭 수나 활성 사용자 수를 측정한 것이 아니며, 그런 성과는 별도 분석 도구에서 확인해야 합니다.

기준 5: 실패 폴백과 사용자 선택도 제품 경로로 검수합니다

도메인 검증이 실패하면 Android는 일반 intent 처리 방식으로 돌아갑니다(C016). 이는 항상 서비스 실패를 의미하지는 않습니다. 웹을 계속 열거나, 사용자가 앱을 고를 수 있거나, 앱의 설정 화면에서 연결을 선택하는 경로가 남을 수 있습니다. 다만 사용자가 기대한 링크가 예기치 않은 화면으로 갈 수 있으므로, 실패 흐름을 숨기지 말고 어떤 화면이 열리는지 확인해야 합니다.

사용자가 특정 도메인을 앱과 연결하도록 직접 선택하는 상황도 있습니다. 공식 문서는 요청 전에 왜 기본 처리자로 연결하려는지 맥락을 설명하라고 안내합니다(C017). 앱이 처리할 이유가 불명확한 URL에서 설정 변경을 유도하면 신뢰를 해칠 수 있습니다. 사용자 선택은 검증을 대신하는 증거가 아니라, 기기별 선택 상태라는 별도 사실로 남겨야 합니다.

마지막 체크는 간단합니다. (1) 운영 중인 host만 선언했는가, (2) 각 host의 서버 파일과 앱 패키지·서명이 일치하는가, (3) 지원 OS별 상태를 읽었는가, (4) 검증 실패 때 웹과 앱 중 어느 흐름이 열리는가, (5) 실제 중요한 URL이 의도한 화면과 오류 처리를 거쳤는가입니다. 이 다섯 기록이 있어야 다음 릴리스에서 경로를 추가하거나 줄일 때 원인을 추적할 수 있습니다.

공식 원문: Android Developers: About deep links, Add Intent filters for App Links, Verify App Links

우리 앱 MVP의 도메인·링크·검수 항목 점검하기

자주 묻는 질문

매니페스트에 `autoVerify`를 넣으면 모든 사용자의 링크가 곧바로 앱으로 열리나요?

아닙니다. 시스템의 검증 시도와 host별 결과, OS 버전, 사용자 선택은 서로 다른 상태입니다. 실제 기기에서 상태와 링크 탭 결과를 함께 확인하세요.

`assetlinks.json`을 한 곳에 두면 모든 서브도메인에 적용되나요?

선언 방식에 따라 다릅니다. Android 문서의 host·wildcard 규칙을 따라, 실제로 선언한 각 host의 게시 위치를 확인해야 합니다.

검증 결과가 `none`이면 즉시 실패로 기록해야 하나요?

아닙니다. 검증 에이전트가 아직 완료되지 않았을 수 있으므로, 충분한 대기 뒤 상태를 다시 확인하고 기기·네트워크 조건을 기록하세요.

App Links가 되면 링크 유입이나 전환 성과도 검증된 건가요?

아닙니다. App Links 검증은 앱과 도메인의 연결 상태입니다. 유입·전환·매출은 별도의 측정 정의와 데이터로 확인해야 합니다.