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 디지털 지문을 복사합니다. 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
파일의 서명과 일치하는지 확인해야 합니다.