快速入門指南

Peter Conn
Peter Conn

「信任的網路活動」設定可能不容易,尤其是您只想顯示網站時,更是如此。本指南將引導您建立使用 Trusted Web Activities 的基本專案,並涵蓋所有相關注意事項。

閱讀完本指南後,您將瞭解:

  • 使用 Bubblewrap 建構使用 Trusted Web Activity 且通過驗證的應用程式。
  • 瞭解何時會使用簽署金鑰。
  • 能夠判斷 Android 應用程式建構時使用的簽章。
  • 瞭解如何建立基本的數位資產連結檔案。

如要按照本指南操作,您需要:

  • 開發電腦上已安裝 Node.js 10 以上版本。
  • 連接並完成開發設定的 Android 手機或模擬器 (如果您使用實體手機,請啟用 USB 偵錯功能)。
  • 開發手機上支援受信任的網路活動的瀏覽器。Chrome 72 以上版本皆可使用。未來也將陸續支援其他瀏覽器。
  • 您想在「受信任的網路活動」中查看的網站。

信任的網路活動可讓 Android 應用程式啟動全螢幕瀏覽器分頁,而不需要任何瀏覽器 UI。這項功能僅限於您擁有的網站,您可以透過設定 Digital Asset Links 來證明這一點。我們稍後會詳細說明

啟動可信任的網頁活動時,瀏覽器會檢查 Digital Asset Links 是否正常運作,這稱為「驗證」。如果驗證失敗,瀏覽器會改回以自訂分頁的形式顯示您的網站。

安裝及設定 Bubblewrap

Bubblewrap 是 Node.js 的一組程式庫和指令列工具 (CLI),可協助開發人員使用信任的網頁活動,在 Android 應用程式中產生、建構及執行漸進式網頁應用程式。

您可以使用下列指令安裝 CLI:

npm i -g @bubblewrap/cli

設定環境

首次執行 Bubblewrap 時,系統會提供自動下載及安裝必要的外部依附元件。建議您讓這項工具執行這項操作,確保依附元件設定正確無誤。請參閱 Bubblewrap 說明文件,瞭解如何使用現有的 Java Development Kit (JDK) 或 Android 指令列工具安裝作業。

初始化並建構專案

如要初始化包裝 PWA 的 Android 專案,請執行 init 指令:

bubblewrap init --manifest=https://my-twa.com/manifest.json

Bubblewrap 會讀取 Web Manifest,要求開發人員確認要在 Android 專案中使用的值,然後使用這些值產生專案。專案產生完成後,請執行以下命令產生 APK:

bubblewrap build

執行

建構步驟會輸出名為 app-release-signed.apk 的檔案。您可以將這個檔案安裝在開發裝置上進行測試,或上傳至 Play 商店發布。

Bubblewrap 提供用於在本機裝置上安裝及測試應用程式的指令,將開發人員裝置連接到電腦後,執行以下操作:

bubblewrap install

或者,您也可以使用 adb 工具。

adb install app-release-signed.apk

應用程式現在應該會顯示在裝置啟動器上。開啟應用程式時,您會發現網站是以自訂分頁而非可信的網頁活動啟動,這是因為我們尚未設定數位資產連結驗證,但首先...

Bubblewrap 的圖形使用者介面 (GUI) 替代方案

PWA Builder 提供圖形使用者介面,可使用 Bubblewrap 程式庫產生信任的網路活動專案。如要進一步瞭解如何使用 PWA Builder 建立可開啟 PWA 的 Android 應用程式,請參閱這篇文章

簽署金鑰注意事項

Digital Asset Links 會考量 APK 使用簽署的金鑰,而且驗證失敗的常見原因為使用的簽章有誤。(請注意,驗證失敗代表網站會以自訂分頁的形式啟動,並在網頁頂端顯示瀏覽器 UI)。Bubblewrap 建構應用程式時,系統會在 init 步驟中建立 APK,並在其中設定金鑰。不過,當您在 Google Play 發布應用程式時,系統可能會為您建立另一個金鑰,具體取決於您選擇如何處理簽署金鑰。進一步瞭解簽署金鑰,以及與 Bubblewrap 和 Google Play 的關聯性

Digital Asset Links 主要包含指向應用程式的網站檔案,以及應用程式中指向您網站的中繼資料。

建立 assetlinks.json 檔案後,請將檔案上傳至網站的 .well-known/assetlinks.json (相對於根目錄),讓瀏覽器能夠正確驗證應用程式。請參閱數位資產連結深入解析,進一步瞭解數位資產連結與簽署金鑰的關係。

正在檢查瀏覽器

受信任的網路活動會嘗試採用使用者預設的瀏覽器。如果使用者的預設瀏覽器支援「Trusted Web Activities」,系統就會啟動該瀏覽器。如果沒有,系統會選擇任何已安裝的瀏覽器,只要該瀏覽器支援 Trusted Web Activities 即可。最後,預設行為會改為使用自訂分頁模式。

也就是說,如果您要對信任的網路活動進行偵錯,請確認您使用的是您認為的瀏覽器。您可以使用下列指令,查看目前使用的瀏覽器:

> adb logcat -v brief | grep -e TWAProviderPicker
D/TWAProviderPicker(17168): Found TWA provider, finishing search: com.google.android.apps.chrome

後續步驟

希望您在按照本指南操作後,能夠順利完成信任的網路活動設定,並掌握足夠的知識,以便在驗證失敗時進行偵錯。如果沒有,請參閱更多網頁開發人員適用的 Android 概念,或針對這些說明文件在 GitHub 回報問題。

接下來,建議您先為應用程式建立圖示。完成後,您可以考慮將應用程式部署至 Play 商店。