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 發布給他們。因此，Google Play 也必須簽署 APK。因此，如果您將應用程式以 AAB 格式上傳至 Play 管理中心，系統會要求您使用 Play 應用程式簽署功能。
    • APK：您可以選擇採用 Play 應用程式簽署功能。強烈建議您啟用 Play 應用程式簽署功能，因為這可提升簽署金鑰的安全性。如前所述，Google Play 很快就會要求所有新應用程式都以 AAB 格式上傳，因此建議您採用 AAB 格式，而非上傳 APK。
  • 自行管理簽署金鑰：如果您選擇自行管理金鑰，且未選擇加入 Play 應用程式簽署計畫，則須自行負責應用程式的簽署金鑰。與 Play 應用程式簽署功能不同，如果您遺失金鑰，就無法重設。因此，如果您遺失應用程式的簽署金鑰，就無法再更新應用程式。

在 bubblewrap init 設定期間，當您進入「Signing key information (5/5)」部分時，系統會提示您輸入「Key store location」和「Key name」，或使用預設值。預設的 KeyStore 位置是專案目錄中的 android.keystore 檔案，預設金鑰名稱則為 android。如果 Bubblewrap 在該位置找不到具有該鍵名現有 KeyStore，就會為您建立一個，並提示您輸入密碼。請記下您輸入的密碼，因為您會在建構程序 (bubblewrap build) 中使用這些密碼，系統會使用金鑰簽署應用程式。如果您選擇加入 Play 應用程式簽署計畫，Bubblewrap 產生的簽署金鑰，以及用於簽署應用程式的金鑰，就會成為「上傳金鑰」。無論您選擇使用 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：

擷取簽署或上傳金鑰的適當 SHA-256 憑證指紋

  • 簽署金鑰：複製「應用程式簽署金鑰憑證」的 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 檔案：

  1. 前往 Play 商店安裝 Asset Link Tool。
  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 Pages) 產生的，您必須新增一行設定，讓 .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. 訊息，請使用 Asset Link Tool 查看應用程式簽名，並確認該簽名與 assetlinks.json 檔案中的簽名相符。