使用查詢參數將資訊傳送至受信任的網路活動

André Cipriani Bandarra

在應用程式中使用受信任的網路活動時，開發人員可能需要將應用程式原生部分的資訊傳遞至漸進式網頁應用程式 (PWA)。

常見的做法是實作自訂分析區隔，以評估從「受信任的網路活動」啟動的安裝量和工作階段。如要導入這項功能，請在啟動網址中加入查詢參數。

修改起始網址

如果傳遞至 PWA 的參數在使用者和啟動時保持不變，可以直接將參數附加至啟動網址。開發人員想要評估 Trusted Web Activity 建立的導覽工作階段數量時，就會發生這種情況。

使用 Bubblewrap

Bubblewrap 工具可協助開發人員為 Android 應用程式建立專案，並透過受信任的網路活動啟動現有 PWA。其中包含程式庫和命令列介面 (CLI)。

建立新專案

使用 Bubblewrap CLI 時，系統會利用 init 指令將專案初始化，並根據網頁資訊清單 (做為參數) 建立預設值：

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

精靈會使用網頁資訊清單的 start_url 做為預設值，並要求使用者確認值，讓開發人員有機會在用於啟動漸進式網頁應用程式的網址中加入額外參數。

修改現有專案

當 Bubblewrap 產生專案時，系統會將該專案的資訊儲存在專案資料夾中的 twa-manifest.json 檔案內。如要修改現有專案的起始網址，開發人員需要修改檔案：

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

接著，重新產生專案檔案，並套用新的起始網址

bubblewrap update

使用 Android Studio

使用 Android Studio 和預設的 LauncherActivity 時，startUrl 會定義為 AndroidManifest.xml 內的中繼標記，而我們可以修改其用來啟動受信任網路活動的網址：

<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 端收集詳細資料，以便將其傳遞至漸進式網頁應用程式。

步驟 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>

結論

使用查詢參數，就能將資訊從原生部分傳送至應用程式的網頁部分。在查詢字串中加入參數後，在網頁上執行的指令碼都能存取該參數，而當使用者前往其他網頁，或開發人員執行共用動作時，系統也可能會將這個參數納入參照連結網址中。

開發人員必須瞭解這些影響，可以使用 link rel=noreferrer 減少影響，或是使用網頁位置 API 清除網址。

目前，受信任的網路活動通訊協定目前並未提供在叫用網頁部分後，與應用程式原生部分交換訊息的機制。

我們認為現有或即將推出的 Web Platform API 適用於開發人員大部分的用途。如果您想尋找即將推出或即將推出的 Web API，請參閱新功能狀態頁面。