Play 앱 서명 이후 assetlinks.json SHA-256: TWA 주소창 해결하기

이 가이드는 한 가지 문제 해결, 즉 웹사이트와 Google Play가 배포하는 빌드 사이의 연결만 다룹니다. TWA를 빌드하는 방법이나 Play의 앱 검토는 다루지 않으며, 이 내용은 아래에 링크된 별도 가이드에서 설명합니다. 여기에 인용한 모든 Google 페이지는 2026년 10월 16일에 확인했으며, 출처는 글 마지막에 정리되어 있습니다.

Play 설치본에만 주소창이 보이는 이유

Chrome은 설치된 앱에 서명한 인증서를 웹사이트가 게시한 지문과 비교하여 TWA를 확인합니다. 이 확인에 실패하면, Chrome의 TWA 빠른 시작 가이드에 따르면 브라우저는 사이트를 Custom Tab(맞춤 탭)으로 표시하는 방식으로 대체됩니다. 이렇게 대체되어 보이는 것이 바로 주소창입니다.

Play 앱 서명을 사용하면 보통 인증서가 두 개입니다. 업로드하는 번들은 업로드 키로 직접 서명하고, Google은 배포하는 APK를 앱 서명 키로 서명합니다. Chrome의 웹 개발자를 위한 Android 개념 페이지에 따르면, Play 스토어에서 다운로드한 앱에 해당하는 지문은 앱 서명 키 지문입니다. 따라서 로컬 인증서만 등록된 파일은 내 책상 위 기기에서는 통과하지만 Play에서 설치한 모든 휴대폰에서는 실패합니다.

두 키가 항상 다른 것은 아닙니다. Android의 앱 서명 문서에는 같은 키가 앱 서명 키와 업로드 키 역할을 모두 하는 구성도 설명되어 있습니다. 따라서 어떤 키를 쓰고 있는지 짐작하지 말고 실제 인증서를 비교하는 것이 해결 방법입니다.

Play Console에서 앱 서명 SHA-256 찾기

현재 Google 문서에는 같은 위치에 대해 두 가지 메뉴 이름이 나와 있습니다. 두 경로 모두 앱의 왼쪽 메뉴에 있는 Protected with Play에서 시작합니다.

일부 Google 페이지를 포함한 오래된 가이드에는 아직 Release > Setup > App signing 또는 Setup > App integrity로 나와 있습니다. 이런 메뉴 이름만 보인다면, 같은 페이지를 예전 이름으로 찾고 있는 것입니다.

직접 보유한 키의 지문 확인하기

업로드 키나 디버그 키의 경우 Java의 keytool이 같은 형식으로 출력합니다. 키 저장소 파일과 별칭을 내 것으로 바꾼 다음, SHA256: 으로 표시된 줄을 복사하세요.

keytool -list -v -keystore my-upload-key.jks -alias upload

여러 앱을 관리한다면 Google Play Developer API로도 Play가 생성한 APK의 인증서 해시를 가져올 수 있습니다(생성된 APK 목록의 certificateSha256Hash 필드). 한 번 수정하는 경우라면 Play Console에서 복사하는 편이 더 간단합니다.

올바른 assetlinks.json 작성 및 제공

이 파일은 구문(statement)으로 이루어진 JSON 배열입니다. TWA의 경우 relation은 delegate_permission/common.handle_all_urls이고, target은 Android 앱입니다. 즉 네임스페이스 android_app, 정확한 애플리케이션 ID, SHA-256 지문 배열로 구성됩니다. 최소 구성 파일은 다음과 같습니다.

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.twa",
      "sha256_cert_fingerprints": [
        "PLAY_APP_SIGNING_KEY_SHA256",
        "UPLOAD_KEY_SHA256"
      ]
    }
  }
]

com.example.twa를 내 애플리케이션 ID로, 각 자리표시자를 콜론으로 구분된 전체 SHA-256으로 바꾸세요. Play 설치본만 확인되면 된다면 두 번째 항목은 삭제하세요. 엄격한 JSON만 허용됩니다. 주석, 후행 쉼표, SHA-1 값은 넣지 마세요.

Google이 요구하는 파일 제공 방식

• 정확한 위치. .well-known의 점까지 포함한 https://your-domain/.well-known/assetlinks.json입니다. example.com과 www.example.com은 서로 다른 출처이므로, 앱이 여는 출처마다 파일을 게시하세요. /app/.well-known/ 같은 하위 디렉터리에 있는 사본은 인정되지 않습니다.
• HTTP 200 직접 응답. Google의 Digital Asset Links 문서에는 다음과 같이 나와 있습니다. “HTTP 200 이외의 서버 응답은 모두 오류로 처리되며, 빈 구문 목록이 됩니다.”
• 리디렉션 없음. 301 및 302 응답은 따라가지 않습니다. http에서 https로 넘어가는 경우와 기본 도메인에서 www로 넘어가는 경우도 포함됩니다.
• 유효한 인증서 체인을 갖춘 HTTPS와 Content-Type: application/json 헤더가 필요합니다. 200으로 응답하는 로그인 페이지나 HTML 오류 페이지는 유효한 파일이 아닙니다.

아무 터미널에서나 실제 응답을 확인하세요. 첫 번째 상태 줄이 200이어야 하고, 콘텐츠 유형은 JSON이어야 하며, 그 앞에 3xx가 없어야 합니다.

curl -sI https://example.com/.well-known/assetlinks.json

지문이 여러 개이거나 앱이 여러 개인 경우

Android의 웹사이트 연결 가이드는 지문 배열에 대해 이렇게 설명합니다. “이 필드는 여러 지문을 지원하므로, 디버그 빌드와 프로덕션 빌드처럼 앱의 여러 버전을 지원하는 데 사용할 수 있습니다.” 업로드 지문이나 디버그 지문은 해당 웹사이트가 실제로 신뢰하기를 원하는 빌드에 대해서만 추가하세요. 별도의 디버그 패키지처럼 애플리케이션 ID가 다른 빌드는 배열 안에 별도의 구문이 필요합니다.

Bubblewrap 또는 PWABuilder로 TWA를 만든 경우

기존 Bubblewrap 프로젝트에서는 Play의 지문을 추가하고 파일을 다시 생성하세요.

bubblewrap fingerprint add "PLAY_APP_SIGNING_KEY_SHA256" --name="Play app signing"
bubblewrap fingerprint list
bubblewrap fingerprint generateAssetLinks

파일을 생성했다고 배포된 것은 아닙니다. 새 assetlinks.json을 웹사이트에 업로드하고 curl로 확인하세요. bubblewrap validate는 PWA를 품질 기준에 따라 검사할 뿐 서명 연결은 확인하지 않으므로, 여기서 통과해도 지문에 대해서는 아무것도 증명하지 않습니다. PWABuilder의 현재 안내도 서명에 대해 같은 점을 짚으며(“.aab 파일을 업로드하면 Google Play가 앱을 다시 서명합니다”), 생성된 파일에 Play의 지문을 추가하라고 안내합니다. 지문 수정은 앱 바이너리가 아니라 웹사이트를 변경하는 작업입니다.

연결을 확인한 다음 Play 설치본 테스트하기

관련된 계층은 네 가지입니다. 웹사이트의 파일, Google의 Digital Asset Links API, Android 자체의 링크 인증, 그리고 TWA를 실행하는 브라우저입니다. 한 계층을 통과했다고 다음 계층까지 증명되지는 않으므로, 순서대로 확인하고 마지막에는 기기에서 확인하세요.

https://digitalassetlinks.googleapis.com/v1/assetlinks:check?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls&target.android_app.package_name=com.example.twa&target.android_app.certificate.sha256_fingerprint=URL_ENCODED_SHA256&key=YOUR_API_KEY

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https%3A%2F%2Fexample.com&relation=delegate_permission%2Fcommon.handle_all_urls

adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

Android Studio의 App Links Assistant(Tools > App Links Assistant)는 Android App Links 연결과 매니페스트를 확인합니다. 이런 용도로는 유용하지만, TWA가 전체 화면으로 열리는지는 알려주지 않습니다. 그것은 기기 테스트로만 알 수 있습니다.

고급: Android 자체의 인증 상태

Android 12 이상에서는 Android의 인증 가이드에 App Links용으로 다음 명령어가 문서화되어 있습니다. 패키지를 바꾸고 처음 두 명령어를 실행한 다음, 몇 분 기다린 후 상태를 확인하세요.

adb shell pm set-app-links --package YOUR_PACKAGE 0 all
adb shell pm verify-app-links --re-verify YOUR_PACKAGE
adb shell pm get-app-links YOUR_PACKAGE

verified는 Android의 도메인 인증 상태를 나타낼 뿐, TWA가 브라우저 UI 없이 열리는지를 뜻하지 않습니다. 1024 이상의 코드는 인증 도구별 오류이며, SHA-256이 잘못되었다는 진단이 아닙니다. TWA 자체에 대해서는 위의 Chrome 로그를 사용하세요.

지문은 일치하는데 주소창이 남는 경우

주소창이 보인다고 해서 SHA-256이 잘못되었다는 증거는 아닙니다. 위의 확인 결과가 linked: true인데도 주소창이 남아 있다면 다음 원인을 차례로 살펴보세요.

수정한 파일이 적용되기까지 걸리는 시간

Google은 TWA에 대해 단일한 대기 시간을 공개하지 않습니다. 여러 캐시가 관여하고 각각 고유한 규칙이 있기 때문입니다.

• 내 서버나 CDN이 아직 이전 파일을 제공하고 있을 수 있습니다. 캐시를 삭제하고 curl로 실제 응답을 확인하세요.
• Digital Asset Links API는 각 응답이 유효한 기간을 maxAge 필드에 표시합니다.
• Android App Links는 별도의 타이밍을 따릅니다. Android의 인증 가이드에 따르면 Android 15 이상에서는 변경 사항이 모든 기기에 반영되기까지 최대 7일이 걸릴 수 있으며, Android 14 이하에서는 일반적으로 앱을 설치하거나 업데이트할 때 파일을 가져옵니다.
• 브라우저가 자체 상태를 보관하고 있을 수 있습니다. 한 개발자는 Chrome 데이터를 삭제한 후 해결되었다고 보고했습니다.

따라서 캐시를 삭제하고, 실제 파일을 확인한 다음, Google Play에서 다시 설치하세요. 테스트 기기에서는 새로 설치하거나 브라우저 데이터를 삭제하면 캐시된 상태가 원인인지 배제할 수 있습니다. 이는 진단 단계일 뿐, 모든 사용자에게 요청할 일은 아닙니다. 정해진 시간을 기준으로 계획을 세우지 마세요.

거부, 검토 및 비공개 테스트

assetlinks.json이 없거나 잘못되었다는 것 자체가 거부 사유로 문서화되어 있지는 않습니다. 문서에 설명된 것은 브라우저 UI가 있는 Custom Tab으로 대체되는 동작입니다. 검토는 별개의 문제입니다. Google Play의 기능 정책에는 “비정상 종료, 강제 종료, 멈춤 등 정상적으로 작동하지 않는 앱은 허용되지 않습니다”라고 되어 있으며, 이는 연결 상태와 관계없이 적용됩니다. 올바른 지문은 주소창 문제를 해결할 뿐 검토 결과를 결정하지는 않습니다. 거부 통지를 받았다면 이메일에 명시된 정책부터 시작하세요.

일부 오래된 글에는 품질 검사를 통과하지 못한 TWA를 Chrome이 비정상 종료시킨다고 나와 있습니다. Chromium은 2023년 5월 4일에 해당 QualityEnforcer 코드를 제거했으므로, 이 조언은 현재 브라우저의 동작이 아니라 과거의 이야기로 여기세요.

거부 통지를 받았다면 통지에 적힌 사유를 기준으로 대응하세요. Broken Functionality 거부 글에서 가장 흔한 기능 관련 통지를 단계별로 설명합니다. 주소창 하나 때문에 TWA를 WebView로 다시 만들지 마세요. AI 빌더로 만든 앱이라면 바이브 코딩 앱을 Google Play에 게시하기에서 프로젝트부터 Play 출시까지 전체 과정을 다룹니다.

자주 묻는 질문

핵심 정리

Play Console 메뉴 이름은 이 페이지에서 가장 빨리 바뀌는 정보입니다. 위의 경로가 내 Console과 더 이상 일치하지 않는다면, Protected with Play 아래에서 Play 앱 서명(Play app signing)을 찾거나 Console에서 app signing을 검색하세요.