이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Android 개념 (웹 개발자용)

Peter Conn

Joyce Toh

Android 및 Google Play를 처음 사용하는 웹 개발자의 경우 몇 가지 세부정보를 알아두어야 합니다. 이에 관한 많은 리소스와 문서가 이미 있습니다 (Android팀 덕분입니다). 여기에서는 몇 가지 중요한 개념과 이러한 개념이 Bubblewrap과 어떤 관련이 있는지 강조 표시합니다.

업로드 키와 서명 키 비교

Bubblewrap을 사용하여 Android App Bundle (AAB) (참고: 2021년 8월부터 Google Play에서는 모든 신규 앱이 Android App Bundle 형식을 사용해야 함)을 생성하거나 APK를 Google Play에 업로드하고 게시하려는 경우 서명 키로 앱에 서명해야 합니다. Google Play에서는 이 문제를 처리할 수 있는 두 가지 옵션을 제공합니다.

Play 앱 서명 (적극 권장): Google에서 앱의 서명 키를 관리하고 보호합니다. 배포를 위해 APK에 서명하는 데 사용됩니다. Play 앱 서명은 두 개의 키를 사용합니다. Google에서 대신 관리하는 '앱 서명 키'와 개발자가 보관하고 비공개로 유지해야 하는 '업로드 키' 업로드 키는 Play Console에 업로드하기 위해 앱에 서명하는 데 사용합니다. 이 시스템에서는 업로드 키가 분실되거나 손상된 경우 Play 지원팀에 문의하여 키를 재설정할 수 있습니다. 현재 Google Play에서는 앱을 AAB 또는 APK로 업로드할 수 있습니다.
- Android App Bundle (AAB): AAB를 Play Console에 업로드하면 APK 빌드 및 생성을 Google Play 스토어로 지연시킵니다. 사용자가 앱을 다운로드하여 설치하면 Google Play에서 서명된 APK로 앱을 배포합니다. 따라서 APK 서명도 Google Play에서 실행해야 합니다. 따라서 기본적으로 앱을 AAB로 Play Console에 업로드하는 경우 Play 앱 서명을 사용해야 합니다.
- APK: APK를 사용하면 Play 앱 서명을 선택할 수 있습니다. Play 앱 서명을 선택하면 서명 키의 보안이 강화되므로 선택하는 것이 좋습니다. 앞서 언급한 대로 곧 Google Play에서 모든 신규 앱을 AAB 형식으로 업로드해야 하므로 APK를 업로드하는 대신 AAB를 업로드하는 것이 좋습니다.
자체 서명 키 관리: 자체 키를 관리하고 Play 앱 서명을 선택하지 않으면 앱의 서명 키에 대한 모든 책임이 개발자에게 있습니다. Play 앱 서명과 달리 키를 분실하면 재설정할 수 없습니다. 따라서 앱의 서명 키를 분실하면 앱을 업데이트할 수도 없게 됩니다.

bubblewrap init 설정 중에 '서명 키 정보 (5/5)' 부분으로 이동하면 '키 저장소 위치' 및 '키 이름'을 입력하거나 기본값을 사용하라는 메시지가 표시됩니다. 기본 키 저장소 위치는 프로젝트 디렉터리의 android.keystore 파일이며 기본 키 이름은 android입니다. Bubblewrap이 해당 위치에서 해당 키 이름의 기존 키 저장소를 찾지 못하면 키 저장소가 생성되고 비밀번호를 입력하라는 메시지가 표시됩니다. 입력한 비밀번호를 알아두세요. 빌드 프로세스 (bubblewrap build)에서 키를 사용하여 앱에 서명할 때 필요합니다. Play 앱 서명을 선택하면 Bubblewrap에서 생성하고 앱에 서명하는 데 사용한 서명 키가 '업로드 키'가 됩니다. Bubblewrap 생성된 키를 서명 또는 업로드 키로 사용하도록 선택하는 경우, 키를 보호하고 비공개로 유지해야 합니다. 버전 관리에 커밋하지 않는 것이 좋습니다. 대신 액세스 권한이 있는 사용자 수를 제한하세요.

디지털 애셋 링크

디지털 애셋 링크는 웹사이트와 Android 앱 간의 관계를 선언하는 데 필요합니다. Bubblewrap에서 생성된 Android 앱이 제대로 인증되고 Chrome 맞춤 탭 대신 신뢰할 수 있는 웹 활동으로 실행되도록 하려면 assetlinks.json 파일에 적절한 키를 추가해야 합니다. 그런 다음 웹사이트의 .well-known/assetlinks.json(루트 기준)에 업로드합니다. assetlinks.json 파일은 다음 형식을 따라야 합니다.

[{
 "relation": ["delegate_permission/common.handle_all_urls"],
 "target": {
   "namespace": "android_app",
   "package_name": "com.your.package_name",
   "sha256_cert_fingerprints": [
     "XX:XX:XX:..."
   ]
 }
}]

SHA256 인증서 지문 가져오기

assetlinks.json 파일을 만들려면 앱의 서명 키와 연결된 SHA 256 인증서 지문이 필요합니다. 중요한 점은 서명 및 업로드 키와 연결된 지문이 다르다는 것입니다. 특히 앱이 Chrome 맞춤 탭으로 실행되는 경우 (브라우저 바가 표시됨) 이 구분을 염두에 두는 것이 중요합니다. 이 경우 assetlinks.json 파일에 적절한 키에 해당하는 지문이 없을 가능성이 높습니다.

로컬에서 앱을 더 쉽게 디버그하려면 assetlinks.json에 서명 및 업로드 인증서의 지문을 모두 포함하는 것이 좋습니다. assetlinks.json 파일에 두 키를 모두 포함하는 방법에 관한 자세한 내용은 아래의 키 추가를 참고하세요.

지문을 가져오는 방법에는 여러 가지가 있으며 다음 섹션에서 자세히 설명합니다. 모두 동일한 지문을 제공하므로 가장 편리한 방법을 선택하세요.

Play Console을 통해

Play 앱 서명 선택 여부에 따라 1~2개의 키가 있을 수 있습니다. 각 키에 적절한 SHA256 지문을 검색하려면 다음 단계를 따르세요.

Play Console로 이동합니다.
관심 있는 앱 선택
왼쪽의 탐색 메뉴에서 출시 아래의 설정 -> 앱 무결성으로 이동합니다.
적절한 키의 SHA256을 복사합니다.

서명 또는 업로드 키에 적절한 SHA256 인증서 지문 검색

서명 키: '앱 서명 키 인증서'의 SHA256 지문을 복사합니다. Google Play에서 서명 키로 서명된 앱을 배포하므로 Google Play 스토어에서 다운로드하는 경우 이 지문은 앱에 해당합니다.
키 업로드: '키 인증서 업로드'의 SHA256 지문을 복사합니다. 이 지문은 앱을 로컬로 설치하는 경우 (예: USB를 통한 ADB를 통해) 앱에 해당합니다. 로컬 머신의 이 APK는 Bubblewrap에서 빌드되었으므로 init 설정 중에 Bubblewrap에서 생성한 키로 서명됩니다. 이 키는 로컬에 설치된 앱의 서명 키일 수 있지만 Play를 통해 앱을 게시하고 나면 실제로는 '업로드 키'가 됩니다.

`keytool` 경유

keytool은 키 및 인증서 관리 도구입니다. Keytool을 사용하여 생성된 APK 또는 AAB Bubblewrap과 연결된 SHA 256 디지털 지문을 추출할 수 있습니다. 이 지문은 로컬 서명 키용이며 앱을 Play에 업로드하고 Play 앱 서명을 선택하면 이 키가 '업로드 키'가 됩니다.

keytool -printcert -jarfile [path to APK or AAB] | grep SHA256

애셋 연결 도구 사용

앱에 적합한 디지털 애셋 링크 파일을 가져오는 또 다른 방법은 애셋 링크 도구를 사용하는 것입니다.

Play 스토어에서 Asset Link 도구를 설치합니다.
동일한 기기에서 Google Play 스토어에서 앱을 다운로드하거나 로컬에 설치합니다.
Asset Link Tool 앱을 열면 기기에 설치된 모든 애플리케이션의 목록이 패키지 이름별로 표시됩니다. 이전에 bubblewrap init 중에 선택한 애플리케이션 ID로 목록을 필터링하고 해당 항목을 클릭합니다.
앱의 서명과 생성된 디지털 애셋 링크가 포함된 페이지가 표시됩니다. 하단의 복사 또는 공유 버튼을 클릭하여 원하는 방식으로 내보냅니다 (예: Google Keep에 저장, 자신에게 이메일로 보내기).

서명 또는 업로드 키에도 이전과 동일한 개념이 적용됩니다. Google Play 스토어에서 앱을 설치한 경우 애셋 링크 도구에서 앱의 서명 키 지문을 가져옵니다. 로컬 머신에서 직접 앱을 설치한 경우 지문은 Bubblewrap에서 생성된 키의 지문입니다.

애셋 링크 파일에 액세스할 수 있는지 확인

이제 업로드했으므로 브라우저에서 애셋 링크 파일에 액세스할 수 있는지 확인합니다. https://example.com/.well-known/assetlinks.json이 방금 업로드한 파일로 확인되는지 확인합니다.

Jekyll 기반 웹사이트

웹사이트가 Jekyll에서 생성된 경우 (예: GitHub 페이지) .well-known 디렉터리가 출력에 포함되도록 구성 줄을 추가해야 합니다. GitHub 도움말에 이 주제에 대한 자세한 내용이 있습니다. 사이트 루트에 _config.yml라는 파일을 만들거나 이미 있는 경우 추가합니다.

# Folders with dotfiles are ignored by default.
include: [.well-known]

키 추가

디지털 애셋 링크 파일에는 둘 이상의 앱이 포함될 수 있으며, 앱마다 하나 이상의 키가 포함될 수 있습니다. 예를 들어 두 번째 키를 추가하려면 애셋 링크 도구를 사용하여 키를 확인하고 두 번째 항목으로 추가하면 됩니다. 이 JSON을 파싱하는 Chrome의 코드는 매우 엄격하므로 목록 끝에 실수로 쉼표를 추가하지 않도록 합니다.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
},{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
}]

문제 해결

Chrome은 디지털 애셋 링크 확인 실패 이유를 로깅하며 adb logcat를 사용하여 Android 기기에서 로그를 볼 수 있습니다. Linux/Mac에서 개발하는 경우 다음을 사용하여 연결된 기기의 관련 로그를 볼 수 있습니다.

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

예를 들어 Statement failure matching fingerprint. 메시지가 표시되면 애셋 링크 도구를 사용하여 앱의 서명을 확인하고 assetlinks.json 파일의 서명과 일치하는지 확인해야 합니다.