整合指南

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

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

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

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

Android Studio 會提示您選擇活動類型。由於可信網頁活動會使用支援程式庫提供的活動,請選擇「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 支援程式庫

如要在專案中設定信任的 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 會顯示提示,要求您再次同步處理專案。按一下「立即同步處理」連結,然後同步處理。

啟動受信任的網路活動

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

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

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

activity 標記插入 application 標記中,即可新增信任的網路活動:

<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 重新啟動應用程式。應用程式現在應以全螢幕模式顯示。

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

  • 套件名稱:第一項資訊是應用程式的套件名稱,與建立應用程式時產生的套件名稱相同。您也可以在 Module build.gradle 中找到這項資訊,位於 Gradle Scripts > build.gradle (Module: app) 底下,並為 applicationId 屬性的值。
  • SHA-256 指紋:Android 應用程式必須經過簽署,才能上傳至 Play 商店。同樣的簽名會透過上傳金鑰的 SHA-256 指紋,建立網站和應用程式之間的連線。

Android 說明文件詳細說明如何使用 Android Studio 產生金鑰。請務必記下金鑰存放區的路徑別名密碼,因為您會在下一個步驟中使用這些資訊。

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

建立圖示

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 裝置的螢幕尺寸像素密度可能不同。為確保 Splash Screen 在所有裝置上都能正常顯示,您必須為每個像素密度產生圖片。

螢幕獨立像素 (dp 或 dip) 的完整說明不在本文討論範圍,但舉例來說,您可以建立 320x320dp 的圖片,這代表任何密度的裝置螢幕上 2x2 英寸的正方形,且等同於 mdpi 密度的 320x320 像素

我們可以根據這些資料,推算出其他像素密度所需的尺寸。以下是像素密度、套用於基礎大小 (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.0 倍 960x960 像素 /res/drawable-xxhdpi/
xxxhdpi 4.0x 1280x1280 像素 /res/drawable-xxxhdpi/

更新應用程式

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

首先,請在 Android 資訊清單 (AndroidManifest.xml) 中新增 content-provider

<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 資源,並指定 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>

我們期待開發人員能透過可信 Web 活動建構出哪些成果。如要提供任何意見回饋,請透過 @ChromiumDev 與我們聯絡。