使用查询参数向 Trusted Web Activity 传递信息

André Cipriani Bandarra

在应用中使用 Trusted Web Activity 时，开发者可能需要将应用的原生部分中的信息传递到渐进式 Web 应用 (PWA)。

一个常见的用例是实现自定义分析细分，以衡量从 Trusted Web Activity 启动的安装和会话。您可以向启动网址添加查询参数来实现此目的。

修改起始网址

如果传递给 PWA 的参数在不同用户和启动期间保持不变，则可以直接将该参数附加到启动网址。例如，当开发者想要衡量通过 Trusted Web Activity 创建的导航会话数量时，就可以使用此用法。

使用 Bubblewrap

Bubblewrap 是一款工具，旨在帮助开发者为 Android 应用创建项目，以便使用 Trusted Web Activity 启动现有 PWA。它包含一个库和一个命令行界面 (CLI)。

创建新项目

使用 Bubblewrap CLI 时，系统会使用 init 命令初始化项目，并根据作为参数提供的 Web 清单创建默认值：

bubblewrap init --manifest https://material.money/manifest.json

该向导将默认使用 Web 清单中的 start_url，并会要求用户确认该值，以便开发者有机会向用于启动渐进式 Web 应用的网址添加额外参数。

显示 Bubblewrap CLI 输出

修改现有项目

Bubblewrap 生成项目时，该特定项目的信息会存储在项目文件夹中名为 twa-manifest.json 的文件中。如需修改现有项目的起始网址，开发者需要修改以下文件：

{
  ...
  "startUrl": "/?utm_source=trusted-web-activity",
  ...
}

然后，重新生成项目文件并应用新的起始网址

bubblewrap update

使用 Android Studio

使用 Android Studio 和默认的 LauncherActivity 时，startUrl 会定义为 AndroidManifest.xml 中的元标记，我们可以通过修改它来更改用于启动 Trusted Web Activity 的网址：

<activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity"
    android:label="@string/app_name">
    ...
    <meta-data android:name="android.support.customtabs.trusted.DEFAULT_URL"
        android:value="https://svgomg.firebaseapp.com/?utm_source=trusted-web-activity" />
    ...
</activity>

动态修改起始网址

在其他情况下，开发者可能希望创建会因用户或会话而变化的参数。在大多数情况下，这涉及从应用的 Android 端收集详细信息，以将其传递给 Progressive Web App。

第 1 步：创建自定义 LauncherActivity

public class CustomQueryStringLauncherActivity extends LauncherActivity {
    private String getDynamicParameterValue() {
        return String.valueOf((int)(Math.random() * 1000));
    }

    @Override
    protected Uri getLaunchingUrl() {
        // Get the original launch Url.
        Uri uri = super.getLaunchingUrl();

        // Get the value we want to use for the parameter value
        String customParameterValue = getDynamicParameterValue();

        // Append the extra parameter to the launch Url
        return uri
                .buildUpon()
                .appendQueryParameter("my_parameter", customParameterValue)
                .build();
    }
}

第 2 步：修改 AndroidManifest.xml 以使用自定义 LauncherActivity

<activity android:name="com.myapp.CustomQueryStringLauncherActivity"
    android:label="@string/app_name">
    ...
    <meta-data android:name="android.support.customtabs.trusted.DEFAULT_URL"
        android:value="https://squoosh.app/?utm_source=trusted-web-activity" />
    ...
</activity>

总结

您可以使用查询参数将信息从应用的原生部分传递到 Web 部分。将参数添加到查询字符串后，网页上运行的脚本将能够访问该参数，并且当用户转到其他网页或开发者实现分享操作时，该参数也可能会包含在引荐来源中。

开发者必须了解这些影响，并可以使用 link rel=noreferrer 或使用 page location API 清理网址来缓解这些影响。

Trusted Web Activity 协议目前未提供在调用 Web 部分后与应用的原生部分交换消息的机制。

我们相信，现有或即将推出的 Web 平台 API 可支持开发者所需的大多数用例。如果您正在寻找新的或即将推出的 Web API，请查看“新功能”状态页面。