整合指南

設定受信任的網路活動時,開發人員無須編寫 Java 程式碼,但必須採用 Android Studio。本指南使用 Android Studio 3.3 版建立。請參閱說明文件,瞭解如何安裝。

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

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

開啟 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 支援程式庫

如要在專案中設定信任的 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 fingerprint 的值會顯示在「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

在網域中放置 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 以上版本,並使用最新版的受信任網路活動支援資料庫

產生啟動畫面的圖片

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.0x 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 資源,並指定 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 與我們聯絡。