受信任的網路活動快速入門指南
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
設定「Trusted Web Activities」可能有些複雜,尤其是當您只想顯示網站時。本指南將引導您建立使用 Trusted Web Activities 的基本專案,並涵蓋所有相關注意事項。
閱讀完本指南後,您將瞭解:
- 使用 Bubblewrap 建構使用受信任的網路活動且通過驗證的應用程式。
- 瞭解何時會使用簽署金鑰。
- 能夠判斷 Android 應用程式建構時使用的簽章。
- 瞭解如何建立基本的數位資產連結檔案。
如要依循本指南,您必須:
- 開發電腦上已安裝 Node.js 10 以上版本
- 已連線並設定好用於開發的 Android 手機或模擬器 (如果使用實體手機,請啟用 USB 偵錯功能)
- 開發手機上支援受信任的網路活動的瀏覽器
- 您要在受信任網路活動中查看的網站
透過信任的網頁活動,Android 應用程式就能在沒有任何瀏覽器 UI 的情況下,啟動全螢幕瀏覽器分頁。這項功能僅限於你擁有的網站,你必須設定 Digital Asset Links 才能證明這一點。我們稍後會詳細說明。
啟動可信任的網頁活動時,瀏覽器會檢查 Digital Asset Links 的檢查作業,這稱為驗證。如果驗證失敗,瀏覽器就會改為以自訂分頁顯示網站。
安裝及設定 Bubblewrap
Bubblewrap 是一組 Node.js 程式庫和指令列工具 (CLI),可協助開發人員使用信任的網路活動,在 Android 應用程式中產生、建構及執行漸進式網頁應用程式。
您可以使用下列指令安裝 CLI:
設定環境
初次執行 Bubblewrap 時,系統會自動下載並安裝必要的外部依附元件。建議您讓這項工具執行此操作,確保依附元件設定正確無誤。請參閱 Bubblewrap 說明文件,瞭解如何使用現有的 Java Development Kit (JDK) 或安裝的 Android 指令列工具。
初始化並建構專案
如要初始化包裝 PWA 的 Android 專案,請執行 init 指令:
Bubblewrap 會讀取 Web Manifest,要求開發人員確認要在 Android 專案中使用的值,然後使用這些值產生專案。專案產生完成後,請執行以下命令產生 APK:
執行
建構步驟會輸出名為 app-release-signed.apk
的檔案。您可以將這個檔案安裝在開發裝置上進行測試,也可以上傳至 Play 商店發布。
Bubblewrap 提供指令,可在本機裝置上安裝及測試應用程式。將開發裝置連接至電腦後,執行以下操作:
或者,您也可以使用 adb 工具。
注意:**adb**
指令列工具位於 **android_sdk/platform-tools/**
的 Android 指令列工具中。
應用程式現已可用於裝置啟動器。開啟應用程式時,您會看到網站是以「自訂分頁」的形式啟動,而非「受信任的網路活動」,這是因為我們尚未設定 Digital Asset Links 驗證程序,但首先要...
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 即可。最後,預設行為會改為使用自訂分頁模式。
也就是說,如果您要對信任的網路活動進行偵錯,請務必使用您認為的瀏覽器。您可以使用下列指令查看目前使用的瀏覽器:
後續步驟
希望您在按照本指南操作後,已成功啟用可靠的網路活動,並具備足夠的知識,能夠在驗證失敗時進行偵錯。如果沒有,請參閱更多 網頁開發人員適用的 Android 概念,或針對這些文件在 GitHub 回報問題。
接下來,建議您先為應用程式建立圖示。完成以上步驟後,您就可以考慮將應用程式部署至 Play 商店。
這個頁面中的內容和程式碼範例均受《內容授權》中的授權所規範。Java 與 OpenJDK 是 Oracle 和/或其關係企業的商標或註冊商標。
上次更新時間:2025-07-27 (世界標準時間)。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["缺少我需要的資訊","missingTheInformationINeed","thumb-down"],["過於複雜/步驟過多","tooComplicatedTooManySteps","thumb-down"],["過時","outOfDate","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["示例/程式碼問題","samplesCodeIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間:2025-07-27 (世界標準時間)。"],[],[],null,["# Trusted Web Activities Quick Start Guide\n\nTrusted Web Activities can be a bit tricky to set up, especially if all you want to do is display your website. This guide will take you through creating a basic project that uses Trusted Web Activities, covering all the gotchas.\n\nBy the end of this guide, you will:\n\n- Have used [Bubblewrap](https://github.com/GoogleChromeLabs/bubblewrap) to build an application that uses a Trusted Web Activity and passes verification.\n- Understand when your signing keys are used.\n- Be able to determine the signature your Android Application is being built with.\n- Know how to create a basic [Digital Asset Links](https://developers.google.com/digital-asset-links/v1/getting-started) file.\n\nTo follow this guide you'll need:\n\n- [Node.js](https://nodejs.org/en/) 10 or above installed on the development computer\n- An Android phone or emulator connected and set up for development ([Enable USB debugging](/studio/debug/dev-options#enable) if you're using a physical phone)\n- A browser that supports Trusted Web Activity on your development phone\n- A website you'd like to view in the Trusted Web Activity\n\nA Trusted Web Activity lets your Android App launch a full screen Browser Tab without any browser UI. This capability is restricted to websites that you own, and you prove this by setting up Digital Asset Links. We'll talk [more about them later](https://developer.chrome.com/docs/android/trusted-web-activity/quick-start#creating-your-asset-link-file).\n\nWhen you launch a Trusted Web Activity, the browser will check that the Digital Asset Links check out, this is called **verification** . If verification fails, the browser will fall back to displaying your website as a [Custom Tab](https://developer.chrome.com/docs/android/custom-tabs).\n\nInstall and configure Bubblewrap\n--------------------------------\n\n[Bubblewrap](https://github.com/GoogleChromeLabs/bubblewrap) is a set of libraries and a command line tool (CLI) for Node.js that helps developers generate, build and run Progressive Web Apps inside Android applications, using Trusted Web Activity.\n\nThe CLI can be installed with the following command:\n\n### Setting up the Environment\n\nWhen running Bubblewrap for the first time, it will offer to automatically download and install the required external dependencies. We recommend letting the tool do this, as it guarantees that the dependencies are configured correctly. Check the [Bubblewrap documentation](https://github.com/GoogleChromeLabs/bubblewrap/blob/main/packages/cli/README.md) to use an existing Java Development Kit (JDK) or Android command line tools installation.\n\nInitialize and build project\n----------------------------\n\nInitializing an Android project that wraps a PWA is done by running the init command:\n\nBubblewrap will read the [Web Manifest](https://developer.mozilla.org/docs/Web/Manifest), ask developers to confirm values to be used in the Android project, and generate the project using those values. Once the project has been generated, generate an APK by running:\n\nRun\n---\n\nThe build step will output a file called `app-release-signed.apk`. This file can be installed on a development device for testing or uploaded to the Play Store for release.\n\nBubblewrap provides a command to install and test the application on a local device. With the development device connected to the computer run:\n\nAlternatively, the [adb](/studio/command-line/adb#move) tool can be used.\n\n**Note** : the `**adb**` command-line tool is located inside the Android command-line tools in `**android_sdk/platform-tools/**`.\n\nThe application is now be available on the device launcher. When opening the application you'll notice that your website is launched as a Custom Tab, not a Trusted Web Activity, this is because we haven't set up our Digital Asset Links validation yet, but first...\n\n### Graphical User Interface (GUI) alternatives for Bubblewrap\n\n[PWA Builder](https://www.pwabuilder.com/) provides a GUI interface that uses the Bubblewrap library to power the generation of Trusted Web Activity projects. Find more instructions on how to use PWA Builder to create an Android App that opens your PWA in [this blog post](https://www.davrous.com/2020/02/07/publishing-your-pwa-in-the-play-store-in-a-couple-of-minutes-using-pwa-builder/).\n\n### A note on signing keys\n\nDigital Asset Links take into account the key that an APK has been signed with and a common cause for verification failing is to use the wrong signature. (Remember, failing verification means you'll launch your website as a Custom Tab with browser UI at the top of the page.) When Bubblewrap builds the application, an APK will be created with a key setup during the `init` step. However, when you publish your app in Google Play, another key may be created for you, depending on how you choose to handle signing keys. Learn more on [signing keys and how they relate to Bubblewrap and Google Play](https://developer.chrome.com/docs/android/trusted-web-activity/android-for-web-devs#upload-vs-signing-key).\n\nSetting up your asset link file\n-------------------------------\n\nDigital Asset Links consist essentially of a file on your website that points to your app and some metadata in your app that points to your website.\n\nAfter creating your `assetlinks.json` file, upload it to your website at .`well-known/assetlinks.json` relative to the root) so that your app can be verified properly by the browser. Check out a [deep dive on Digital Asset Links](https://developer.chrome.com/docs/android/trusted-web-activity/android-for-web-devs#digital-asset-links) for more information on how it relates to your signing key.\n\nChecking your browser\n---------------------\n\nA Trusted Web Activity will try to adhere to the user's default choice of browser. If the user's default browser supports Trusted Web Activities, it will be launched. Failing that, if any installed browser supports Trusted Web Activities, it will be chosen. Finally, the default behavior is to fall back to a Custom Tabs mode.\n\nThis means that if you're debugging something to do with Trusted Web Activities, you should make sure you're using the browser you think that you are. You can use the following command to check which browser is being used:\n\nNext Steps\n----------\n\nHopefully, if you've followed this guide, you'll have a working Trusted Web Activity and have enough knowledge to debug what's going on when verification fails. If not, have a look at more [Android concepts for web developers](https://developer.chrome.com/docs/android/trusted-web-activity/android-for-web-devs) or file a GitHub issue against [these docs](https://github.com/google/WebFundamentals/issues).\n\nFor your next steps, I'd recommend you start off by [creating an icon for your app](/studio/write/image-asset-studio#launcher). With that done, you can consider deploying your app to the Play Store."]]