整合指南

André Cipriani Bandarra

注意：注意：現在提供更簡單的Trusted Web Activities 快速入門指南。

設定信任的網頁活動不需要開發人員撰寫 Java 程式碼，但需要使用 Android Studio。本指南是使用 Android Studio 3.3 建立。請參閱說明文件，瞭解如何安裝。

建立信任的網路活動專案

使用信任的網頁活動時，專案必須指定 API 16 以上版本。

注意： 本節將引導您在 Android Studio 中設定新專案。如果您已熟悉這項工具，可以直接跳到「取得信任的網路活動程式庫」一節。

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

Android Studio 會提示您選擇活動類型。由於可信 Web 活動會使用支援程式庫提供的活動，請選擇「Add No Activity」，然後按一下「Next」。

在下一個步驟中，精靈會提示您設定專案。以下是各欄位的簡短說明：

• 名稱：在 Android 啟動器中用於應用程式的名稱。
• 套件名稱：Play 商店和 Android 裝置上 Android 應用程式的專屬 ID。如要進一步瞭解為 Android 應用程式建立套件名稱的相關規定和最佳做法，請參閱說明文件。
• 儲存位置：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
    }
}

接下來，我們會在專案中加入 Trusted Web Activity Support Library。將新的依附元件新增至 dependencies 區段：

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

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

啟動受信任的網路活動

如要設定 Trusted Web Activity，請編輯 Android 應用程式資訊清單。

在「Project Navigator」中，依序展開「app」和「manifests」，然後按兩下 AndroidManifest.xml 開啟檔案。

我們要求 Android Studio 在建立專案時不要將任何 Activity 新增至專案，因此資訊清單會是空白的，並且只包含應用程式標記。

在 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 Activities 的內容有兩個相關資訊：

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

注意： 在這個階段執行專案時，自訂分頁的網址列仍會顯示在畫面頂端。這不是錯誤。

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

移除網址列

如要移除網址列，可信任的網頁活動必須在 Android 應用程式和網站之間建立關聯。

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

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

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

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

<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 應用程式與網站的關係。無須建立網站至應用程式驗證，即可對這部分的關係進行偵錯，這點很有幫助。

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

啟用偵錯模式

1. 在開發裝置上開啟 Chrome，前往 chrome://flags，搜尋名為「在未解鎖的裝置上啟用命令列」的項目，並將其變更為「已啟用」，然後重新啟動瀏覽器。
2. 接著，在作業系統的 Terminal 應用程式中使用 Android Debug Bridge (透過 Android Studio 安裝)，並執行下列指令：

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

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

注意： 您可能需要強制關閉 Chrome，才能使用正確的指令列重新啟動 Chrome。依序前往「Android 設定」>「應用程式和通知」>「Chrome」，然後點選「強制停止」。

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

為了建立關聯，開發人員需要從應用程式收集下列 2 項資訊：

• 套件名稱：第一項資訊是應用程式的套件名稱，與建立應用程式時產生的套件名稱相同。您也可以在 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 指紋的值會列印在「憑證」指紋部分下方。以下是輸出內容範例：

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) 提供。

注意： AssetLinks 檔案必須位於 /.well-known/assetlinks.json 底下，也就是網域的根目錄，因為 Chrome 只會在該處尋找該檔案。

正在建立圖示

Android Studio 建立新專案時，會附帶預設的圖示。開發人員應自行建立圖示，讓應用程式在 Android 啟動器中與其他應用程式有所區隔。

Android Studio 包含 Image Asset Studio，可提供必要工具，讓您為應用程式所需的每個解析度和形狀建立正確的圖示。

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

產生已簽署的 APK

在網域中放置 assetlinks 檔案，並在 Android 應用程式中設定 asset_statements 標記後，下一步就是產生已簽署的應用程式。再次提醒，這項操作的步驟已廣泛記錄。

您可以使用 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) 的詳細說明不在本文的討論範圍，但其中一種範例可以建立 320x320dp 的圖片，也就是在各種密度的裝置螢幕上呈現 2x2 英寸的正方形，相當於 mdpi 密度的 320 x 320 像素。

我們可以根據這些資料，推算出其他像素密度所需的大小。以下是像素密度、套用於基礎大小 (320x320dp) 的倍數、產生的像素大小，以及應在 Android Studio 專案中新增圖片的位置清單。

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

注意： 如要建立所有圖片大小，您也可以使用單一向量可繪項目。Vector Asset Studio 提供工具，可協助開發人員將 SVG 轉換為 Android 向量可繪項目。

更新應用程式

啟動畫面的圖片已產生，現在是時候在專案中新增必要的設定了。

首先，請將 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>

注意： 建立提供者時，請務必變更 android:authorities 屬性，因為兩個應用程式無法在裝置上擁有相同的權限。

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

<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>

我們期待開發人員能透過可信任的網頁活動建構出什麼樣的應用程式。如有任何意見，歡迎透過 @ChromiumDev 與我們聯絡。