如果您是第一次使用 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 管理中心。如果上傳金鑰遺失或遭到盜用,您可以與 Play 支援團隊聯絡,藉此重設上傳金鑰。目前,Google Play 可讓您以 AAB 或 APK 格式上傳應用程式:
- Android App Bundle (AAB):將 AAB 上傳至 Play 管理中心時,您需要將建構和產生 APK 的作業延後到 Google Play 商店。當使用者下載及安裝應用程式時,Google Play 會以已簽署的 APK 的形式將應用程式發布給使用者。因此,APK 的簽署也必須由 Google Play 進行。因此,根據預設,如果您以 AAB 格式將應用程式上傳到 Play 管理中心,則必須使用 Play 應用程式簽署功能。
- APK:使用 APK 時,您可以選擇加入 Play 應用程式簽署計畫。強烈建議您選擇加入 Play 應用程式簽署計畫,因為這麼做可以提高簽署金鑰的安全性。如先前所述,Google Play 不久後就會要求所有新應用程式都以 AAB 格式上傳,因此我們建議您這麼做,而不要上傳 APK。
- 管理自己的簽署金鑰:如果您選擇自行管理金鑰,但不選擇加入 Play 應用程式簽署計畫,您就必須對應用程式的簽署金鑰全權負責。與 Play 應用程式簽署不同的是,金鑰遺失後無法重設。因此,遺失應用程式的簽署金鑰會導致您也無法再更新應用程式。
在 bubblewrap init
設定期間,當您看到「Signing key information (5/5)」(簽署金鑰資訊 (5/5)) 部分時,系統會提示您輸入「Key store location」(金鑰商店位置) 和「Key name」(金鑰名稱),或使用預設值。預設金鑰儲存位置是專案目錄中的檔案 android.keystore
,預設金鑰名稱為 android
。如果 Bubblewrap 在位置中找不到擁有該金鑰名稱的現有 KeyStore,就會為您建立金鑰庫並提示您輸入密碼。請記下您在建構過程中 (bubblewrap build
) 輸入的密碼,因為您會在建構過程中使用這些金鑰簽署應用程式。如果您選擇加入 Play 應用程式簽署計畫,則 Bubblewrap 產生並用於簽署應用程式的簽署金鑰會變成「上傳金鑰」。無論您選擇使用對話框產生的金鑰做為簽署或上傳金鑰,請務必妥善保管金鑰,並確保金鑰的私密性。我們不建議您將其設定為版本管控。因此請限制具存取權的使用者。
Digital Asset Links
您必須使用 Digital Asset Links 宣告網站和 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 管理中心
視您是否已加入 Play 應用程式簽署計畫而定,可能會有一或兩個金鑰。如要擷取每個金鑰的適當 SHA256 指紋:
- 前往 Play 管理中心。
- 選取你感興趣的應用程式
- 在左側導覽選單中的「版本」下方,依序前往「設定」->「應用程式完整性」。
- 複製適當的金鑰 SHA256:
簽署金鑰:複製「應用程式簽署金鑰憑證」的 SHA256 指紋。由於 Google Play 會發布以簽署金鑰簽署的應用程式,因此如果您從 Google Play 商店下載該應用程式,這個指紋就會對應至您的應用程式。
上傳金鑰:複製「上傳金鑰憑證」的 SHA256 指紋。如果您在本機安裝應用程式 (例如透過 USB 透過 ADB 安裝),這個指紋就會對應至您的應用程式。您本機電腦上的 APK 是由 Bubblewrap 建構,因此,您也會透過系統為您建立的金鑰 (在
init
設定期間) 進行簽署。請注意,這可能是您在本機安裝應用程式的簽署金鑰,但當您透過 Play 發布應用程式後,這個金鑰就會成為「上傳金鑰」。
走keytool
keytool 是金鑰和憑證管理工具。您可以使用 keytool 擷取與 APK 或 AAB Bubblewrap 相關聯的 SHA 256 指紋。請注意,這個指紋用於本機簽署金鑰,如果您將應用程式上傳至 Play 並選擇加入 Play 應用程式簽署計畫,這組金鑰就會成為「上傳金鑰」。
keytool -printcert -jarfile [path to APK or AAB] | grep SHA256
透過素材資源連結工具
另一種取得應用程式正確 Digital Asset Links 檔案的方法是使用 Asset Link Tool:
- 前往 Play 商店安裝資產連結工具。
- 在同一個裝置上,從 Google Play 商店下載應用程式,或在本機安裝應用程式。
- 開啟 Asset Link Tool 應用程式,系統會依套件名稱列出裝置上安裝的所有應用程式。按照您先前在
bubblewrap init
期間選擇的應用程式 ID 篩選清單,然後按一下該項目。 - 系統隨即會顯示一個頁面,列出應用程式簽名和系統產生的 Digital Asset Link。按一下底部的「複製」或「分享」按鈕,即可任意匯出 (例如將內容儲存至 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]
新增更多金鑰
Digital Asset Link 檔案可包含多個應用程式,而每個應用程式則可包含多個金鑰。舉例來說,如要新增第二個金鑰,只要使用素材資源連結工具判斷金鑰,並將其新增為第二個項目即可。在 Chrome 中剖析此 JSON 的程式碼相當嚴格,因此請勿意外在清單結尾加上額外半形逗號。
[{
"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 會記錄 Digital Asset Links 驗證失敗的原因,而您可以透過 adb logcat
在 Android 裝置上查看記錄。如果您在 Linux/Mac 上進行開發,可以查看來自於已連結裝置的相關記錄:
> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links
舉例來說,如果您看到 Statement failure matching fingerprint.
訊息,則應使用資產連結工具查看應用程式的簽名,並確保該簽名與 assetlinks.json
檔案中相符。