Android 概念 (適用於網頁開發人員)

Peter Conn
Peter Conn
X GitHub
Joyce Toh
Joyce Toh
GitHub

如果您是第一次使用 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 宣告網站和 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 指紋：

  1. 前往 Play 管理中心。
  2. 選取你感興趣的應用程式
  3. 在左側導覽選單中的「版本」下方，依序前往「設定」->「應用程式完整性」。
  4. 複製適當的金鑰 SHA256：

針對簽署或上傳金鑰擷取適當的 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：

  1. 前往 Play 商店安裝資產連結工具。
  2. 在同一個裝置上，從 Google Play 商店下載應用程式，或在本機安裝應用程式。
  3. 開啟 Asset Link Tool 應用程式，系統會依套件名稱列出裝置上安裝的所有應用程式。按照您先前在 bubblewrap init 期間選擇的應用程式 ID 篩選清單，然後按一下該項目。
  4. 系統隨即會顯示一個頁面，列出應用程式簽名和系統產生的 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 檔案中相符。