本頁面由 Cloud Translation API 翻譯而成。

整合指南

André Cipriani Bandarra

Twitter GitHub Glitch Mastodon 首頁

設定可信網路活動時，開發人員不必編寫 Java 程式碼，但必須使用 Android Studio。本指南是使用 Android Studio 3.3 版建立。參閱安裝方法說明文件。

建立「受信任的網路活動」專案

使用 Trusted Web Activities 時，專案必須指定 API 16 以上目標。

開啟 Android Studio，然後按一下「Start a new Android Studio project」。

Android Studio 會提示選擇 Activity 類型。由於「Trusted Web Activities」會使用支援資料庫提供的活動，因此請選擇「Add No Activity」，然後點選「Next」。

接著，精靈會提示您設定專案。以下是每個欄位的簡短說明：

名稱：應用程式在 Android 啟動器上採用的名稱。
套件名稱：Play 商店和 Android 裝置上 Android 應用程式的專屬 ID。請參閱說明文件，進一步瞭解為 Android 應用程式建立套件名稱的規定和最佳做法。
「Save location」(儲存位置)：Android Studio 會在檔案系統中建立專案的位置。
語言：專案不需編寫任何 Java 或 Kotlin 程式碼。選取 Java 做為預設值。
最低 API 級別：支援資料庫至少需要 API 級別 16。請在上方選取任一 API 16 版本。

由於我們不會使用免安裝應用程式或 AndroidX 構件，因此請將其餘核取方塊保持未勾選狀態，然後按一下「Finish」。

取得信任的網路活動支援資料庫

如要在專案中設定 Trusted Web Activity 程式庫，您必須編輯應用程式建構檔案。在「Project Navigator」中找到「Gradle Scripts」部分。有兩個名為 build.gradle 的檔案，可能會令人困惑，而括號中的說明則有助於識別正確的檔案。

我們要尋找的檔案是在名稱旁邊顯示「Module」模組的檔案。

Trusted Web Activities 程式庫會使用 Java 8 功能，而第一項變更會啟用 Java 8。在 android 區段底部新增 compileOptions 區段，如下所示：

android {
        ...
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
    }
}

下一步會將「信任的網路活動支援資料庫」新增至專案。將新的依附元件新增至 dependencies 區段：

dependencies {
    implementation 'com.google.androidbrowserhelper:androidbrowserhelper:2.2.0'
}

Android Studio 會顯示提示，要求再次同步處理專案。按一下「Sync Now」連結，然後進行同步處理。

啟動受信任的網路活動

如要設定受信任的網路活動，只要編輯 Android 應用程式資訊清單即可。

在「Project Navigator」中，展開「app」部分，然後點選「manifests」，然後按兩下 AndroidManifest.xml 開啟檔案。

由於我們在建立 Android Studio 時要求不要將任何活動加入專案，因此資訊清單是空白的，且只包含應用程式標記。

在 application 標記中插入 activity 標記，藉此新增信任的網路活動：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.example.twa.myapplication">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme"
        tools:ignore="GoogleAppIndexingWarning">
        <activity
            android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">

           <!-- Edit android:value to change the url opened by the Trusted Web Activity -->
           <meta-data
               android:name="android.support.customtabs.trusted.DEFAULT_URL"
               android:value="https://airhorner.com" />

           <!-- This intent-filter adds the Trusted Web Activity to the Android Launcher -->
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>

           <!--
             This intent-filter allows the Trusted Web Activity to handle Intents to open
             airhorner.com.
           -->
           <intent-filter>
               <action android:name="android.intent.action.VIEW"/>
               <category android:name="android.intent.category.DEFAULT" />
               <category android:name="android.intent.category.BROWSABLE"/>

               <!-- Edit android:host to handle links to the target URL-->
               <data
                 android:scheme="https"
                 android:host="airhorner.com"/>
           </intent-filter>
        </activity>
    </application>
</manifest>

新增至 XML 的標記是標準的 Android 應用程式資訊清單。「Trusted Web Activity」的情境中有兩項相關資訊：

meta-data 標記會告知「信任的網路活動」應開啟哪個網址。將 android:value 屬性變更為您要開啟的 PWA 網址。在這個範例中為 https://airhorner.com。
「第二個」intent-filter標記可讓信任的網路活動攔截開啟 https://airhorner.com 的 Android 意圖。data 標記中的 android:host 屬性必須指向「受信任網路活動」開啟的網域。

下一節將說明如何設定 Digital AssetLinks 以驗證網站與應用程式的關係，並移除網址列。

移除網址列

如要使用「Trusted Web Activities」，您必須建立 Android 應用程式與網站之間的關聯，才能移除網址列。

這項關聯是透過 Digital Asset Links 建立，而且關聯必須以這兩種方式建立，並從應用程式連結至網站，以及從網站連結到應用程式。

您可將應用程式設為進行網站驗證，並將 Chrome 設為略過網站驗證，以便進行偵錯。

為應用程式與網站建立關聯

開啟字串資源檔案 app > res > values > strings.xml，並新增下方的 Digital AssetLink 陳述式：

<resources>
    <string name="app_name">AirHorner Trusted Web Activity</string>
    <string name="asset_statements">
        [{
            \"relation\": [\"delegate_permission/common.handle_all_urls\"],
            \"target\": {
                \"namespace\": \"web\",
                \"site\": \"https://airhorner.com\"}
        }]
    </string>
</resources>

請變更 site 屬性的內容，使其符合「受信任網路活動」開啟的結構定義和網域。

返回 Android 應用程式資訊清單檔案 AndroidManifest.xml，新增 meta-data 標記以連結至陳述式，但這次會做為 application 標記的子項：

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.twa.myapplication">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="asset_statements"
            android:resource="@string/asset_statements" />

        <activity>
            ...
        </activity>

    </application>
</manifest>

現在，Android 應用程式與網站之間已經建立好關係。您不必建立網站對應用程式驗證作業，就可以針對這個部分的關係進行偵錯。

以下說明如何在開發裝置上測試這項功能：

啟用偵錯模式

在開發裝置上開啟 Chrome，前往 chrome://flags，搜尋名為在非 Root 權限的裝置上啟用指令列的項目，並將其變更為 ENABLED，然後重新啟動瀏覽器。
接著，在作業系統的終端機應用程式中，使用以 Android Studio 安裝的 Android Debug Bridge，並執行下列指令：

adb shell "echo '_ --disable-digital-asset-link-verification-for-url=\"https://airhorner.com\"' > /data/local/tmp/chrome-command-line"

關閉 Chrome，並從 Android Studio 重新啟動應用程式。現在應用程式應會以全螢幕模式顯示。

建立網站與應用程式之間的關聯

開發人員需要從應用程式收集 2 項資訊才能建立關聯：

Package Name：第一個資訊是應用程式的套件名稱。這和建立應用程式時產生的套件名稱相同。您也可以在「Module」build.gradle 的「Gradle Scripts」>「build.gradle (Module: app)」中找到，這是 applicationId 屬性的值。
SHA-256 指紋：Android 應用程式必須登入才能上傳到 Play 商店。相同的簽章會利用上傳金鑰的 SHA-256 指紋建立網站和應用程式之間的連線。

Android 說明文件會詳細說明如何使用 Android Studio 產生金鑰。請務必記下金鑰存放區的「path」、「alias」和「passwords」，因為在下個步驟中將會用到。

使用 keytool 並執行下列指令，擷取 SHA-256 指紋：

keytool -list -v -keystore [path] -alias [alias] -storepass [password] -keypass [password]

SHA-256 指紋的值會顯示在「Certificate」指紋區段下方。以下是輸出範例：

keytool -list -v -keystore ./mykeystore.ks -alias test -storepass password -keypass password

Alias name: key0
Creation date: 28 Jan 2019
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Issuer: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Serial number: ea67d3d
Valid from: Mon Jan 28 14:58:00 GMT 2019 until: Fri Jan 22 14:58:00 GMT 2044
Certificate fingerprints:
   SHA1: 38:03:D6:95:91:7C:9C:EE:4A:A0:58:43:A7:43:A5:D2:76:52:EF:9B
   SHA256: F5:08:9F:8A:D4:C8:4A:15:6D:0A:B1:3F:61:96:BE:C7:87:8C:DE:05:59:92:B2:A3:2D:05:05:A5:62:A5:2F:34
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3

將這兩項資訊備妥後，請前往 assetlinks 產生器並填寫欄位，然後點選「Generate Statement」。複製產生的陳述式，並從網址 /.well-known/assetlinks.json 的網域提供該陳述式。

建立圖示

當 Android Studio 建立新專案時，專案會顯示預設圖示。開發人員會希望建立自己的圖示，藉此在 Android 啟動器中與其他應用程式做出區別。

Android Studio 包含 Image Asset Studio，可提供所需工具，讓您針對應用程式所需的各種解析度和形狀建立正確圖示。

在 Android Studio 中，前往 File > New > Image Asset 並選取 Launcher Icons (Adaptative and Legacy)，然後按照精靈中的步驟為應用程式建立自訂圖示。

產生已簽署的 APK

在您的網域和 Android 應用程式設定的 asset_statements 標記備妥 assetlinks 後，下一步要產生已簽署的應用程式。同樣地，這些步驟已廣泛記錄。

您可以利用 ADB，將輸出 APK 安裝到測試裝置上：

adb install app-release.apk

如果驗證步驟失敗，您可以使用 Android Debug Bridge (從 OS 的終端機，且已連接測試裝置) 查看錯誤訊息。

adb logcat | grep -e OriginVerifier -e digital_asset_links

上傳 APK 後，您就可以將應用程式上傳到 Play 商店。

新增啟動畫面

從 Chrome 75 版起，Trusted Web Activities 將支援啟動畫面。只要在專案中加入幾個新的圖片檔和設定，即可設定啟動畫面。

請務必更新至 Chrome 75 以上版本，並使用最新版的 Trusted Web Activity Support Library。

正在產生啟動畫面圖片

Android 裝置可能會有不同的螢幕大小和像素密度。為確保啟動畫面在所有裝置上都能正常顯示，您必須為每個像素密度產生圖片。

「顯示獨立像素」(dp 或 dip) 的完整說明超出本文的範圍，但其中一個範例是建立在 mdpi 密度裝置螢幕上 2x2 英寸的正方形圖片，相當於 320x320 像素。

我們由此取得其他像素密度所需的尺寸。下方清單包含像素密度、基本大小的調節係數 (320x320dp)、產生的像素大小，以及圖片應在 Android Studio 專案中新增的位置。

密度	乘數	大小	專案位置
mdpi (基準)	1.0 倍	320x320 像素	/res/drawable-mdpi/
ldpi	0.75 倍	240x240 像素	/res/drawable-ldpi/
hdpi	1.5x	480x480 像素	/res/drawable-hdpi/
xhdpi	2.0 倍	640x640 像素	/res/drawable-xhdpi/
xxhdpi	3.0 倍	960x960 像素	/res/drawable-xxhdpi/
xxxhdpi	4.0 倍	1280x1280 像素	/res/drawable-xxxhdpi/

更新應用程式

產生啟動畫面的圖片後，接下來請將必要的設定新增至專案。

首先，請將 content-provider 新增至 Android 資訊清單 (AndroidManifest.xml)。

<application>
    ...
    <provider
        android:name="androidx.core.content.FileProvider"
        android:authorities="com.example.twa.myapplication.fileprovider"
        android:grantUriPermissions="true"
        android:exported="false">
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/filepaths" />
    </provider>
</application>

接著，新增 res/xml/filepaths.xml 資源，並指定 Twitter 啟動畫面的路徑：

<paths>
    <files-path path="twa_splash/" name="twa_splash" />
</paths>

最後，將 meta-tags 新增至 Android 資訊清單，以自訂 LauncherActivity：

<activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">
    ...
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_IMAGE_DRAWABLE"
               android:resource="@drawable/splash"/>
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_BACKGROUND_COLOR"
               android:resource="@color/colorPrimary"/>
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_FADE_OUT_DURATION"
               android:value="300"/>
    <meta-data android:name="android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY"
               android:value="com.example.twa.myapplication.fileprovider"/>
    ...
</activity>

確認 android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY 標記的值與 provider 標記中 android:authorities 屬性的值相符。

將 LauncherActivity 設為透明

此外，請為 LauncherActivity 設定半透明主題，確保 LauncherActivity 是透明，避免在啟動前顯示白色畫面：

<application>
    ...
    <activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity"
              android:theme="@android:style/Theme.Translucent.NoTitleBar">
    ...
    </activity>
</application>

我們很期待看到開發人員透過 Trusted Web Activity 建構的應用程式。如要提供任何意見回饋，請透過 @ChromiumDev 與我們聯絡。