KappS 지식 베이스 · 블로그

Android 앱 링크 2026: 단계별 검증 튜토리얼

블로그 튜토리얼

Android 앱 링크는 Google가 소유권 증명으로 인정하는 유일한 딥링크 방식입니다. 앱이 처리할 HTTPS 호스트를 선언하고, 해당 호스트에 디지털 자산 링크 명세를 게시하면, Android가 둘의 일치를 확인한 뒤에야 브라우저 대신 앱을 엽니다. 결과를 좌우하는 것은 두 가지 산출물, 즉 직접 관리하는 /.well-known/assetlinks.json 파일과 그 안의 SHA-256 서명 지문이며, 대부분의 실패는 특별한 원인이 아니라 이 중 하나가 조금 어긋나서 발생합니다.

이 튜토리얼은 실제 작업이 진행되는 순서를 따릅니다. autoVerify 인텐트 필터 선언, assetlinks.json 문장 목록 게시, Play 앱 서명이 빌드를 재서명할 때 올바른 지문 선택, 검증 상태 설치 및 확인, 프로덕션에서 흔한 실패 진단, 사용자에게 거짓말하지 않는 폴백 설계, 그리고 키 교체와 도메인 이전 전반에 걸쳐 앱 링크 검증을 유지하는 방법까지 다룹니다. 이 모든 것의 바탕이 되는 원칙은 하나입니다. 검증은 도메인과 앱의 소유자가 같다는 약속이므로, 통과하는 유일한 정당한 방법은 실제로 둘 다를 소유하는 것입니다.


1. 검증된 링크가 증명하는 것과 증명하지 않는 것

세 가지 개념이 뒤섞이는데, 이를 구분하면 대부분의 잘못된 설계 결정을 막을 수 있습니다.

  • 딥링크는 앱 내 화면을 여는 모든 인텐트를 말합니다. myapp://product/42 같은 커스텀 스킴으로 전달될 수 있는데, 기기의 어떤 앱이든 같은 스킴을 등록할 수 있으므로 악성 앱이 동일한 스킴을 선점해 URL을 대신 받아갈 수 있습니다.
  • An App Link is an HTTPS URL — https://shop.example.com/product/42 — that Android has verified you are entitled to handle, because that host publishes a statement naming your package and your signing certificate. The user sees a normal web URL, the browser can always open it, and only one app can win the verification.
  • 웹 폴백은 앱이 설치되어 있지 않을 때 브라우저에서 동일한 URL을 여는 것입니다. 잘 설계된 링크 전략은 세 요소를 모두 일치시켜, 앱 설치 여부와 관계없이 URL이 원하는 콘텐츠로 연결되도록 합니다.

인증이 하지 않는 일: 앱 설치 여부를 증명하지 않고, 도메인 콘텐츠에 대한 어떤 권리도 부여하지 않으며, 인증을 대체하지도 않습니다. 화면에 계정 데이터가 표시된다면 서버에서의 토큰 검증이 여전히 그것을 보호합니다. 인증은 "이 앱이 이 호스트의 링크를 열어도 되는가"에만 답합니다 — 그 이상은 아닙니다.

실질적인 결과 하나: 커스텀 스킴은 내부 핸드오프용으로만 사용하고, 비밀번호 재설정이나 결제 리다이렉트에는 절대 의존하지 마세요. 스킴 소유권은 강제할 수 없기 때문입니다.

2. 1단계 — 매니페스트에 autoVerify 인텐트 필터 선언

AndroidManifest.xml에서 시작하세요. 필터는 android:autoVerify="true"가 포함된 https 필터여야 하며, VIEW 액션과 DEFAULT 및 BROWSABLE 카테고리가 모두 필요합니다:

<intent-filter android:autoVerify="true"> <action android:name="android.intent.action.VIEW" /> <category android:name="android.intent.category.DEFAULT" /> <category android:name="android.intent.category.BROWSABLE" /> <data android:scheme="https" android:host="shop.example.com" /> </intent-filter>

실무에서 성패를 가르는 세부 사항:

  • 호스트당 필터 하나. 검증은 호스트별로 평가되며, Google의 안내는 도메인마다 별도의 <intent-filter>를 두라는 것입니다. 다섯 개 호스트를 하나의 필터로 묶으면 잘못된 호스트 하나가 나머지까지 망칩니다.
  • 호스트는 문자 그대로입니다. android:host는 와일드카드를 허용하지 않습니다. 하위 도메인은 별도 필터로 처리하고, android:path, android:pathPrefix, android:pathPattern로 범위를 좁혀 앱이 렌더링할 수 없는 URL을 차지하지 않도록 하세요.
  • http는 검증할 수 없습니다. 자동 검증에 참여하는 것은 https뿐입니다. http 필터를 그대로 두면 선택 창만 중복으로 뜹니다.
  • 라우팅하는 경로만 선언하세요. 앱이 세 개의 경로만 처리하는데 필터가 전체 호스트와 일치하면 나머지 모든 URL이 빈 화면으로 이어집니다. 그리고 이 동작은 크래시 대시보드보다 스토어 리뷰에서 훨씬 먼저 드러납니다.

앱이 마케팅 도메인과 앱 도메인을 모두 처리한다면, 공유에 어떤 것을 표준으로 삼을지 의도적으로 결정하세요. 추가하는 모든 호스트는 게시할 파일이자 동기화를 유지해야 할 인증서입니다.

3. 2단계 — /.well-known/assetlinks.json 게시

명세서 목록은 HTTPS를 통해 정확히 하나의 경로에 있으며, 앞단에 리디렉션이 없습니다:

https://shop.example.com/.well-known/assetlinks.json

본문은 문장의 JSON 배열입니다. 호스트의 모든 URL을 처리하는 일반 앱이라면 문장 하나로 충분합니다:

[{ "relation": ["delegate_permission/common.handle_all_urls"], "target": { "namespace": "android_app", "package_name": "com.example.shop", "sha256_cert_fingerprints": [ "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5" ] } }]

여러 패키지 또는 여러 인증서가 있는 하나의 패키지는 동일한 배열에 명령문을 더 추가할 뿐입니다. 제공 방식의 세부 사항은 내용만큼 중요합니다.

  • 콘텐츠 유형. application/json으로 제공하세요. 일부 Android 버전과 일부 CDN 엣지 구성은 이에 엄격합니다.
  • 리디렉션 금지. 파일 앞에 301 또는 302가 있으면 가져오기가 실패하며, 기기에서는 조용히 실패합니다. 가장 흔한 호스팅 실수로, 사이트 전체의 "HTTPS 강제" 또는 "후행 슬래시 제거" 규칙이 이를 조용히 망가뜨립니다.
  • 인증도, 봇 차단도 없습니다. Google의 검증기는 파일을 익명으로 가져옵니다. WAF 챌린지나 지역 차단이 있으면 JSON이 있어야 할 자리에 HTML 오류 페이지가 반환됩니다.
  • 유효한 JSON, 주석 없음. 끝에 붙은 쉼표 하나나 잘못 들어간 // 주석 하나만으로도 파일 전체와 그 안의 모든 구문이 무효가 됩니다.

Before you debug anything on the device, fetch the file the way the verifier would: curl -sI https://shop.example.com/.well-known/assetlinks.json should show 200 and no Location header, and the body should parse. Google publishes a statement list generator and tester that will validate the structure and the fingerprint format for you — use it before shipping.

4. 3단계 — 기기가 실제로 인식하는 지문 사용하기

대부분의 검증이 실패하는 지점이며, 그 이유는 Play 앱 서명에 있습니다. 등록하면 Google가 앱 서명 키를 보관하고 전달하는 모든 산출물에 다시 서명합니다. 따라서 사용자 기기에 설치된 인증서는 앱 서명 인증서이며, 빌드 머신에 있는 업로드 키가 아닙니다.

  • Play 설치 수의 경우 앱 서명 키 SHA-256 인증서가 필요하며, Play Console의 앱 무결성 → 앱 서명에서 확인할 수 있습니다("앱 서명 키 인증서" 항목).
  • 로컬 및 사이드로드 빌드는 업로드 키 또는 디버그 키로 서명되며 해당 지문이 필요합니다. keytool -list -v -keystore <keystore>로 읽고 SHA-256 줄을 복사하세요.
  • 둘 다 등록하세요. 앱 서명 인증서와 업로드 인증서를 동일한 sha256_cert_fingerprints 배열에 함께 넣는 것은 정상이며 권장되는 방식입니다. Play 설치 시 검증이 이루어지면서 QA 빌드도 계속 작동합니다.

같은 영역에 함정이 두 가지 더 있습니다. 디버그 키스토어를 사용하는 경우 그 지문은 생성한 머신에만 해당하므로 자체 테스트에는 괜찮지만 게시 파일에서는 쓸모가 없습니다. 또한 Play의 키 업그레이드를 사용하면 인증서가 변경되므로, 업그레이드가 배포되기 전에 문장 목록을 반드시 갱신해야 합니다. 그렇지 않으면 기존 설치에서는 계속 작동하지만 신규 설치에서는 링크가 깨집니다.

지문은 다시 입력하지 말고 콘솔에서 복사하세요. 16진수 두 자리가 뒤바뀌면 유효한 JSON이면서 200으로 서비스되지만, 어디에서도 오류 메시지 없이 검증에 실패하는 파일이 만들어집니다.

5. 4단계 — 설치 후 실제 검증 상태 확인하기

검증은 앱 설치 시 한 번, 업데이트 후 다시 한 번 시도됩니다. 따라서 테스트 중인 채널에서 앱을 설치해야 합니다. Play 내부 테스트로 설치한 경우와 업로드 서명된 빌드를 adb install한 경우는 동작이 다릅니다.

Android 12 이상에서는 플랫폼에 직접 물어보세요:

adb shell pm get-app-links com.example.shop

도메인별 보고서가 제공됩니다. 도메인, 사용자의 승인 여부, 그리고 검증 상태가 표시되며, 명세 목록이 일치하면 verified, 일치하지 않으면 denied 또는 legacy_failure로 나타납니다. 구버전에서는 이에 해당하는 도메인 검증 기록 덤프가 제공됩니다.

adb shell dumpsys package d

호스트가 거부로 표시되는데 방금 파일을 수정했다면, 무작정 재설치하지 말고 새로 시도하도록 강제하세요:

adb shell pm set-app-links --package com.example.shop --domain shop.example.com all

그다음 사용자가 실제로 수행하는 흐름을 테스트하세요. 브라우저에 직접 입력한 링크, 메일 클라이언트에서 탭한 링크, 다른 앱 안의 링크는 항상 같은 방식으로 처리되지 않으며, 그중 하나만 선택 화면을 거칠 수 있습니다. 시스템 설정의 앱 기본으로 열기 화면도 확인하세요. 사용자가 인증된 링크를 꺼둘 수 있으므로, 코드는 그 상황에서도 깨지지 않아야 합니다.

6. 5단계 — 실제로 마주하게 될 실패 원인을 진단하세요

거의 모든 프로덕션 장애는 다섯 가지 범주 중 하나에 속합니다. 이 순서대로 확인하세요. 각 항목은 몇 초면 됩니다.

  1. 잘못된 지문. 파일은 정상적으로 파싱되고 호스트도 맞으며, 명세서의 인증서는 업로드 키인데 기기에는 Play 서명 빌드가 설치되어 있는 경우입니다. 콘솔 지문을 파일과 한 글자씩 대조하세요.
  2. 리다이렉트 또는 잘못된 콘텐츠 유형. curl -sI 실행 시 3xx, text/html 또는 CDN에 캐시된 오류 페이지가 표시됩니다. 헤더를 수정하고 캐시를 비운 후 다시 확인하세요.
  3. 패키지 이름 또는 호스트 불일치. 화이트라벨 빌드를 위해 애플리케이션 ID가 변경되었거나, 필터에 더 이상 파일을 제공하지 않는 스테이징 호스트가 남아 있는 경우입니다. 매니페스트에서 모든 호스트를 검색해 각각에 유효한 명세서가 있는지 확인하세요.
  4. 확인이 실행되지 않았습니다. 오프라인 상태에서 설치했거나, 설치 후 앱을 한 번도 실행하지 않은 경우입니다. 연결된 상태에서 앱을 한 번 열고 pm get-app-links를 다시 실행하세요.
  5. 사용자 재정의. 설정에서 해당 도메인이 비활성화된 경우입니다. 몇 달 전일 수도 있고, OEM 마이그레이션 도구 때문일 수도 있습니다. pm set-app-links … all은 테스트용으로 재설정하지만, 실제 사용자에게는 강제가 아니라 안내가 해결책입니다.

릴리스 점검표에 한 줄짜리 스모크 테스트를 넣어 두세요. 파일을 가져오고, 파싱하고, 지문이 현재 콘솔에 표시된 값과 같은지 확인하는 것입니다. 이 점검을 건너뛴 도메인 이전이나 키 업그레이드는 작동하던 링크 설정이 조용히 죽는 바로 그 경로입니다.

7. 6단계 — 사실대로 알리는 대체 로직 구축

앱 링크는 앱을 선호 처리자로 만들 뿐, 유일한 처리자로 만들지는 않습니다. 웹 쪽을 먼저 설계하세요. 항상 존재하는 경우이기 때문입니다.

  • URL은 앱 없이도 열려야 합니다. 설치했을 때만 작동하는 공유 링크는 깨진 링크이며, 이를 인덱싱하는 크롤러도 망가뜨립니다.
  • 감지한 뒤 제안하세요 — 가로채지 마세요. "앱에서 열기"와 스토어 링크가 있는 작은 배너가, 의도적으로 브라우저를 원하는 사용자를 가두는 자동 리디렉션보다 전환율이 높습니다.
  • 딥링크 경로를 웹 경로와 동일하게 유지하세요. 앱이 /product/42를 렌더링한다면, 같은 경로의 웹 페이지도 같은 상품을 보여줘야 합니다. 만들지 않고 미루는 매핑 테이블이 다음 분기에 문제를 일으킵니다.
  • 설치 대기 사례를 처리하세요. 신규 사용자가 설치 후 공유된 항목에 도착하는 지연된 딥링크에는 서버 측 또는 설치 리퍼러 메커니즘이 필요합니다. 대부분의 팀이 사용하던 Firebase Dynamic Links는 지원이 종료되었으므로, 호스팅 서비스를 가정하지 말고 Install Referrer API나 자체 구현을 계획하세요.

그리고 검증을 보이지 않게 만들려는 유혹을 이겨내세요. 앱이 URL을 렌더링할 수 없다면 브라우저가 처리하도록 두는 것이 앱 측의 "찾을 수 없음" 화면보다 나은 결과이며, 도메인의 SEO도 그대로 유지됩니다.

8. 릴리스와 도메인 전반에 걸쳐 검증 유지하기

검증은 일회성 설정이 아닙니다. 매니페스트, 게시된 파일, 스토어가 실제로 서명하는 인증서라는 세 가지 움직이는 요소 간의 상시 합의입니다. 이 중 하나라도 건드리는 일은 출시 점검표 항목입니다.

  • 주요 업그레이드 또는 재서명. 새 인증서로 assetlinks.json을 업데이트하고 배포 전에 게시하세요. 그런 다음 이전 버전이 완전히 종료될 때까지 기존 인증서를 목록에 유지하세요.
  • 도메인 변경. 새 호스트에 먼저 문구를 게시하고, 매니페스트 변경은 그다음에 배포하세요. 파일이 없는 호스트를 가리키는 필터는 링크를 즉시 오프라인으로 만듭니다.
  • 브랜드 및 지역 도메인. 각 호스트는 별도의 선언이자 별도의 파일입니다. 새 지역 도메인이 파일 없이 배포되지 않도록 배포를 자동화하세요.
  • 소유권 확인. 이 파일은 해당 도메인을 귀하가 통제한다는 공개 선언입니다. 조직이 소유하고 운영하는 도메인에만 게시하고, 다른 당사자를 대신해 그들의 선언문을 호스팅하지 마세요. 바로 그 패턴이 어뷰징 탐지가 찾는 대상이며, 도메인과 앱 계정 모두를 위험에 빠뜨립니다.

매니페스트 필터, 게시된 JSON 템플릿, 현재 지문을 단일 소스에서 생성해 한곳에 보관하세요. 이 셋을 각각 수동으로 편집하면 두 번의 릴리스 주기 안에 서로 어긋나기 시작합니다.

9. KappS의 위치

저희는 출시의 운영 측면을 담당합니다. 계정, 릴리스, 스토어 기록을 플랫폼 심사를 견딜 수 있는 상태로 유지하는 일, 즉 규정을 준수하는 자료를 준비하고 제출하는 일이며, 결코 검증을 우회하지 않습니다. 링크 검증에서 이는 보통 다음을 뜻합니다:

  • 릴리스 위생. 콘솔, 빌드, 게시된 진술 목록 간에 인증서와 애플리케이션 ID가 일관되어야 하며, 그래야 기기가 보는 지문이 문서화한 지문과 일치합니다.
  • 계정 준비 상태. 개발자 인증, 결제 프로필, 세금 정보가 계정의 법인과 일치해야 하며, 그렇지 않으면 무관한 심사로 인해 출시가 지연될 수 있습니다.
  • 도메인 및 호스팅 검토. well-known 경로가 리디렉션, WAF 챌린지, 캐시된 오류 페이지 없이 실제로 JSON을 제공하는지 확인하는 작업입니다.

저희가 하지 않는 일: 고객이 소유하지 않은 도메인에 대한 문구 게시, 지문 위조, 앱이 권리 없는 호스트를 자기 것이라고 주장하도록 돕는 일입니다. 인증은 바로 그런 행위로부터 사용자를 보호하기 위해 존재하며, 저희가 제공하는 서비스가 아닙니다.

출처(공식 문서): Android Developers — Android 앱 링크 확인, Android 앱 링크 추가, 디지털 자산 링크 명세, Play Console 고객센터 — 앱 서명 키 인증서 및 키 업그레이드, Android Developers — 앱 링크용 adb shell pm 명령어.

개발자 계정을 대규모로 운영하시나요? 운영 업무를 저희가 처리합니다.

클릭하여 파일 선택 · 우클릭 → 붙여넣기, 또는 Ctrl/⌘+V로 스크린샷 붙여넣기

파일을 이 상자로 끌어다 놓아도 됩니다.

입력하신 이메일로 답변드립니다. 고객님의 정보는 KappS에만 보관됩니다.

✔ 제출 완료

메시지를 접수했습니다. 24시간 이내에 답변드리겠습니다.


← 수정으로 돌아가기