How to Build Trusted Web Activities (TWA) for Android with Android Studio

Original source: https://developers.google.com/web/updates/2019/02/using-twa Original title: Using Trusted Web Activities Translator: Xie Pan Proofreader: Zhang Zhuo

Trusted Web Activities are a new way to integrate web apps, allowing you to combine a PWA with an Android app using a Custom Tabs‑based protocol.

Code references:

TrustedWebUtils Android Support Library API reference [1]

Sample Trusted Web Activity application [2]

How Trusted Web Activities differ

The content is trusted – the app and the website are owned by the same developer, verified via Digital Asset Links .

Trusted Web Activities are rendered by the Web (the user's browser) and can run fullscreen; the web content must first work in a browser.

Chrome updates independently of Android and works back to Jelly Bean, reducing APK size and ensuring a modern web runtime. (From Lollipop onward, WebView can also be updated independently.)

The app cannot directly access the web content’s cookies or localStorage, but data can be passed via URL query parameters, custom HTTP headers, or intent URIs .

Navigation between Web and native is performed via Activities ; each Activity is either provided by the web or by Android.

For testing, Trusted Web Activities currently have no content requirements, but they may need the Add to Home Screen permission. You can audit this using Lighthouse’s “user can be prompted to Add to Home screen” check.

If the user’s Chrome version does not support Trusted Web Activities, Chrome will fall back to a simple toolbar based on Custom Tabs. Other browsers can implement the TWA protocol, but we recommend using the default browser that provides the required features.

Getting Started

Setting up a Trusted Web Activity does not require writing Java code, but you need Android Studio. This guide assumes Android Studio 3.3. See the installation documentation.

Create Trusted Web Activity Project

The project must target API level 16 or higher.

Open Android Studio and click Start a new Android Studio project .

When prompted to choose an Activity type, select Add No Activity and click Next .

On the next screen, configure the project fields:

Name: The application name displayed on the Android desktop.

Package Name: The unique identifier for the app on the Play Store and Android devices. See the documentation for package name requirements.

Save location: Where Android Studio will create the project directory.

Language: No Java or Kotlin code is required; select Java as the default.

Minimum API Level: The support library requires at least API 16. Choose API 16 or higher.

Ignore other options and click Finish .

Obtain TWA Support Library

To add the TWA library, edit several files. In the Project Navigator, locate the Gradle Scripts section.

The first file is the project‑level build.gradle :

<code>allprojects {
   repositories {
       google()
       jcenter()
       maven { url "https://jitpack.io" }
   }
}</code>

Sync the project and click Sync Now .

The second file is the module‑level build.gradle . Enable Java 8 support by adding the following inside the android block:

<code>android {
    ...
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}</code>

Then add the TWA support library dependency:

<code>dependencies {
   implementation 'com.github.GoogleChrome.custom-tabs-client:customtabs:d08e93fce3'
}</code>

Click Sync Now again.

Add TWA Activity

Modify the Android App Manifest to declare the TWA activity.

Open AndroidManifest.xml (app → manifests) and add an activity inside the application tag:

<code><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">

        <activity android:name="android.support.customtabs.trusted.LauncherActivity">
            <!-- Edit android:value to change the URL opened by the TWA -->
            <meta-data
                android:name="android.support.customtabs.trusted.DEFAULT_URL"
                android:value="https://airhorner.com" />

            <!-- This intent‑filter adds the TWA 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 TWA to handle intents to open the target URL -->
            <intent-filter>
                <action android:name="android.intent.action.VIEW" />
                <category android:name="android.intent.category.DEFAULT" />
                <category android:name="android.intent.category.BROWSABLE" />
                <data android:scheme="https" android:host="airhorner.com" />
            </intent-filter>
        </activity>
    </application>
</manifest></code>

The meta-data tag tells the TWA which URL to open; change the android:value to your PWA’s URL. The second intent-filter enables the TWA to intercept Android intents for that URL.

Remove URL Bar

Trusted Web Activities require an association between the Android app and the website to hide the URL bar. This is established via Digital Asset Links in two directions: from the app to the website and from the website to the app.

Establish App‑to‑Website Association

Open app/res/values/strings.xml and add a Digital Asset Links statement:

<code><resources>
    <string name="app_name">AirHorner TWA</string>
    <string name="asset_statements">
        [{
            "relation": ["delegate_permission/common.handle_all_urls"],
            "target": {
                "namespace": "web",
                "site": "https://airhorner.com"
            }
        }]
    </string>
</resources></code>

Then add a corresponding meta-data entry in the application tag of AndroidManifest.xml :

<code><application
    ...>
    <meta-data
        android:name="asset_statements"
        android:resource="@string/asset_statements" />
    <!-- existing activity definition -->
</application></code>

At this point the app is linked to the website; you can skip the website‑to‑app verification for debugging.

Enable Debug Mode

On a development device, open Chrome and navigate to chrome://flags . Search for “Enable command line” and set it to ENABLED , then restart the browser.

Next, use Android Debug Bridge to disable Digital Asset Link verification for the test URL:

<code>adb shell "echo '_ --disable-digital-asset-link-verification-for-url=\"https://airhorner.com\"' > /data/local/tmp/chrome-command-line"</code>

Close Chrome and relaunch the app from Android Studio; it should now display fullscreen.

Establish Website‑to‑App Association

To create the reverse association you need the app’s package name and its SHA‑256 fingerprint.

Find the package name (applicationId) in Gradle Scripts → build.gradle (Module: app) . Generate the SHA‑256 fingerprint by signing the app and running:

<code>keytool -list -v -keystore <path_to_keystore> -alias <alias_name> -storepass <store_password> -keypass <key_password></code>

Copy the SHA‑256 value from the “Certificate fingerprints” section.

Use the Digital Asset Links generator, fill in the package name and SHA‑256, and click “Generate Statement”. Place the resulting JSON in the website’s /.well-known/assetlinks.json file.

Packaging

After configuring assetlinks on the website and asset_statements in the Android app, generate a signed APK following the documentation.

Install the APK on a test device with:

<code>adb install app-release.apk</code>

If verification fails, view logs with:

<code>adb logcat | grep -e OriginVerifier -e digital_asset_links</code>

Once the signed APK is built, you can upload the app to the Play Store.

References

TrustedWebUtils Android Support Library API reference: https://developer.android.com/reference/android/support/customtabs/TrustedWebUtils.html

Sample Trusted Web Activity application: https://github.com/GoogleChromeLabs/svgomg-twa

Digital Asset Links: https://developers.google.com/digital-asset-links/v1/getting-started

Intent URIs: https://developer.chrome.com/multidevice/android/intents

Add to Home Screen: https://developers.google.com/web/fundamentals/app-install-banners/#criteria

Lighthouse: https://developers.google.com/web/tools/lighthouse/

Android Studio: https://developer.android.com/studio/

Installation documentation: https://developer.android.com/studio/install

Manifest package documentation: https://developer.android.com/guide/topics/manifest/manifest-element#package

Jitpack: https://jitpack.io/

Java 8 support: https://developer.android.com/studio/write/java8-support

Android App Manifest: https://developer.android.com/guide/topics/manifest/manifest-intro

Digital Asset Links (again): https://developers.google.com/digital-asset-links/v1/getting-started

From app to website: https://developers.google.com/digital-asset-links/v1/create-statement

From website to app: https://developer.android.com/training/app-links/verify-site-associations#web-assoc

Android Debug Bridge: https://developer.android.com/studio/command-line/adb

Generate signing key: https://developer.android.com/studio/publish/app-signing#generate-key

Keytool: https://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html

Asset Links generator: https://developers.google.com/digital-asset-links/tools/generator

Signing documentation: https://developer.android.com/studio/publish/app-signing#sign-apk

Upload to Play Store: https://developer.android.com/studio/publish/upload-bundle