集成指南

安德烈·奇普里亚尼·班达拉
André Cipriani Bandarra

设置 Trusted Web Activity 不需要开发者编写 Java 代码,但要求使用 Android Studio。本指南是使用 Android Studio 3.3 创建的。请参阅关于如何安装该工具的文档

创建 Trusted Web Activity 项目

使用 Trusted Web Activity 时,项目必须以 API 16 或更高级别为目标平台。

打开 Android Studio,然后点击 Start a new Android Studio project

Android Studio 将提示您选择 activity 类型。由于 Trusted Web Activity 使用支持库提供的 Activity,因此请选择 Add No Activity,然后点击 Next

下一步,向导将提示您提供项目的配置。以下是对每个字段的简短说明:

  • Name:您的应用在 Android 启动器中使用的名称。
  • 软件包名称:Play 商店和 Android 设备上 Android 应用的唯一标识符。如需详细了解为 Android 应用创建软件包名称的要求和最佳做法,请参阅文档
  • Save location:Android Studio 在文件系统中创建项目的位置。
  • 语言:项目不需要编写任何 Java 或 Kotlin 代码。 选择 Java 作为默认设置。
  • 最低 API 级别:支持库至少需要 API 级别 16。选择上述任一版本的 API 16。

请勿选中其余复选框,因为我们不会使用免安装应用或 AndroidX 工件,然后点击 Finish

获取 Trusted Web Activity 支持库

如需在项目中设置 Trusted Web Activity 库,您需要修改 Application build 文件。在项目导航器中查找 Gradle Scripts 部分。 有两个名为 build.gradle 的文件,可能会有点令人困惑,括号中的说明有助于识别正确的文件。

我们要查找的文件是名称旁边带有模块 Module 的文件。

Trusted Web Activity 库使用 Java 8 功能,并且第一项更改支持 Java 8。在 android 部分的底部添加 compileOptions 部分,如下所示:

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

下一步会将 Trusted Web Activity 支持库添加到项目中。向 dependencies 部分添加新的依赖项:

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

Android Studio 将显示提示,要求您再次同步项目。点击 Sync Now 链接并进行同步。

启动 Trusted Web Activity

可通过修改 Android 应用清单来设置 Trusted Web Activity。

项目导航器上,展开 app 部分,然后展开 manifests,然后双击 AndroidManifest.xml 以打开该文件。

由于我们要求 Android Studio 在创建项目时不要向其添加任何 activity,因此清单为空,仅包含应用标记。

通过将 activity 标记插入 application 标记来添加 Trusted Web 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 的上下文,有两条相关信息:

  1. meta-data 标记会告知 Trusted Web Activity 应打开哪个网址。将 android:value 属性更改为您要打开的 PWA 的网址。在此示例中为 https://airhorner.com
  2. 第二个 intent-filter 标记允许 Trusted Web Activity 拦截打开 https://airhorner.com 的 Android intent。data 标记内的 android:host 属性必须指向由 Trusted Web Activity 打开的网域。

下一部分将介绍如何设置 Digital AssetLinks 以验证网站和应用之间的关系,并移除网址栏。

移除网址栏

Trusted Web Activity 需要将 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 属性的内容,以匹配 Trusted Web Activity 打开的架构和网域。

返回 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,搜索名为在未取得 root 权限的设备上启用命令行的项,并将其更改为已启用,然后重启浏览器。
  2. 接下来,在操作系统的“终端”应用中,使用 Android 调试桥(已随 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 项信息:

  • Package Name:第一条信息是应用的软件包名称。这与创建应用时生成的软件包名称相同。您也可以在 Module build.gradle 内的 Gradle Scripts > build.gradle (Module: app) 下找到它,它是 applicationId 属性的值。
  • SHA-256 指纹:Android 应用必须经过签名才能上传到 Play 商店。该签名还用于通过上传密钥的 SHA-256 指纹在网站和应用之间建立连接。

Android 文档详细介绍了如何使用 Android Studio 生成密钥。请务必记下密钥库的 pathaliaspasswords,下一步中会用到。

使用 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 调试桥从操作系统的终端以及连接测试设备来检查错误消息。

adb logcat | grep -e OriginVerifier -e digital_asset_links

生成上传 APK 后,您现在可以将应用上传到 Play 商店了。

添加启动画面

Chrome 75 开始,Trusted Web Activity 支持启动画面。 您可以通过向项目添加一些新的图片文件和配置来设置启动画面。

请务必更新到 Chrome 75 或更高版本,并使用最新版 Trusted Web Activity 支持库

为启动画面生成图片

Android 设备可能具有不同的屏幕尺寸像素密度。为了确保启动画面在所有设备上都能正常显示,您需要针对每种像素密度生成相应图片。

与屏幕无关的像素(dp 或 dip)的完整说明不在本文的讨论范围内,但可以创建一个尺寸为 320x320dp 的图像,它表示在任意密度的设备屏幕上一块 2x2 英寸的方形图片,在 mdpi 或 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.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>

我们期待看到开发者使用 Trusted Web Activity 构建的应用。如有任何反馈,请通过 @ChromiumDev 与我们联系。