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

Android 개념 (웹 개발자용)

Peter Conn

Joyce Toh

Android 및 Google Play를 처음 사용하는 웹 개발자라면 알아야 할 몇 가지 세부정보가 있습니다. Android팀 덕분에 이를 위한 많은 리소스와 문서가 이미 있지만 여기서는 몇 가지 중요한 개념과 이러한 개념이 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): Play Console에 AAB를 업로드하면 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 build) 중에 필요하므로 입력한 비밀번호를 기록해 둡니다. Play 앱 서명을 선택하면 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 앱 서명 선택 여부에 따라 한두 개의 키를 사용할 수 있습니다. 각 키에 대해 적절한 SHA256 디지털 지문을 검색하려면 다음 안내를 따르세요.

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

서명 또는 업로드 키에 적합한 SHA256 인증서 디지털 지문을 가져옵니다.

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

`keytool` 경유

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

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

애셋 링크 도구를 통해

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

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

서명 또는 업로드 키의 경우 이전과 동일한 개념이 적용됩니다. Google Play 스토어에서 앱을 설치했다면 Asset Link 도구에서 앱 서명 키의 디지털 지문을 가져옵니다. 로컬 머신에서 앱을 직접 설치했다면 생성된 키 버블랩의 디지털 지문입니다.

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

이제 업로드가 완료되었으니 브라우저에서 애셋 링크 파일에 액세스할 수 있는지 확인하세요. 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 파일의 서명과 일치하는지 확인해야 합니다.