集成指南

André Cipriani Bandarra

注意：注意：现在，我们提供了更简单的 Trusted Web Activity 快速入门指南。

设置可信 Web activity 不需要开发者编写 Java 代码，但需要使用 Android Studio。本指南使用 Android Studio 3.3 创建。请参阅有关如何安装该插件的文档。

创建 Trusted Web Activity 项目

使用可信 Web 活动时，项目必须以 API 16 或更高级别为目标平台。

注意 ：本部分将指导您在 Android Studio 上设置新项目。如果您已熟悉该工具，可以直接跳至获取 Trusted Web Activity 库部分。

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

Android Studio 会提示您选择 activity 类型。由于可信 Web 活动使用支持库提供的 activity，因此请选择 Add No Activity，然后点击 Next。

下一步，向导会提示您为项目配置。以下是对每个字段的简要说明：

• 名称：Android 启动器中将用于应用的名称。
• 软件包名称：Play 商店和 Android 设备上 Android 应用的唯一标识符。如需详细了解为 Android 应用创建软件包名称的要求和最佳实践，请参阅文档。
• 保存位置：Android Studio 将在文件系统中创建项目的位置。
• 语言：此项目无需编写任何 Java 或 Kotlin 代码。选择 Java 作为默认选项。
• 最低 API 级别：支持库至少需要 API 级别 16。选择 API 16 或更高版本。

由于我们不会使用 Instant Apps 或 AndroidX 工件，因此请勿选中其余复选框，然后点击完成。

获取 Trusted Web Activity 支持库

如需在项目中设置可信 Web 活动库，您需要修改应用 build 文件。在 Project Navigator 中，查找 Gradle Scripts 部分。 有两个名为 build.gradle 的文件，这可能会让人有些困惑，括号中的说明有助于识别正确的文件。

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

Trusted Web Activities 库使用 Java 8 功能，第一个更改会启用 Java 8。将 compileOptions 部分添加到 android 部分底部，如下所示：

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

如需设置 Trusted Web Activity，请修改 Android 应用清单。

在 Project Navigator 中，展开 app 部分，然后展开 manifests，并双击 AndroidManifest.xml 以打开该文件。

由于我们在创建项目时要求 Android Studio 不要向项目添加任何 activity，因此清单是空的，只包含 application 标记。

将 activity 标记插入 application 标记中，以添加可信 Web 活动：

<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 打开的网域。

注意： 在此阶段运行项目时，自定义标签页中的网址栏仍会显示在屏幕顶部。这不是 bug。

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

移除网址栏

可信 Web activity 需要在 Android 应用和网站之间建立关联，才能移除网址栏。

此关联是通过 Digital Asset Link 创建的，并且必须通过两种方式建立关联，即从应用到网站和从网站到应用。

您可以将应用设置为网站验证，并将 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 权限的设备上启用命令行的项目，将其更改为 ENABLED，然后重启浏览器。
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 重新启动应用。现在，应用应以全屏模式显示。

注意 ：您可能需要强制关闭 Chrome，以便其使用正确的命令行重启。依次前往 Android 设置 > 应用和通知 > Chrome，然后点击强行停止。

建立从网站到应用的关联

为了创建关联，开发者需要从应用中收集以下 2 项信息：

• 软件包名称：第一个信息是应用的软件包名称。此名称与创建应用时生成的软件包名称相同。您也可以在模块 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 生成器，填写相应字段，然后点击生成声明。复制生成的声明，并通过网址 /.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 调试桥，在操作系统的终端中检查是否有错误消息，并连接测试设备。

adb logcat | grep -e OriginVerifier -e digital_asset_links

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

添加启动画面

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

请务必更新到 Chrome 75 或更高版本，并使用最新版可信 Web 活动支持库。

为启动画面生成图片

Android 设备可以具有不同的屏幕尺寸和像素密度。为了确保启动画面在所有设备上都能正常呈现，您需要为每种像素密度生成图片。

本文无法详细介绍与显示屏无关的像素 (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 倍	480 x 480 像素	/res/drawable-hdpi/
xhdpi	2.0 倍	640x640 像素	/res/drawable-xhdpi/
xxhdpi	3 倍	960x960 像素	/res/drawable-xxhdpi/
xxxhdpi	4.0 倍	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>

我们期待看到开发者使用 Trusted Web Activity 构建出什么样的应用。如需提供任何反馈，请通过 @ChromiumDev 与我们联系。