Spotted a bug? Have a great idea? Help us make google.dev great!

Trusted Web Activities provide a new way to integrate your web content into your Android app, using a full-screen Chrome Activity.

How do Trusted Web Activities work?

A Trusted Web Activity runs Chrome, in full screen, inside an Android application, without any browser UI visible.

This a powerful capability and is only allowed when the site being opened and the Android application belong to the same developer. This validation is achieved through Digital AssetLinks.

What you'll build

In this codelab, you are going to use an existing Progressive Web App, https://airhorner.com/, and create an Android application that opens it inside a Trusted Web Activity.

What you'll learn

  • How to set up and launch a Trusted Web Activity from an Android application.
  • How to set up Digital Asset Links to validate ownership of both the web and the Android app.

What you'll need

This codelab is focused on building a Trusted Web Activity. Even though you won't be required to write any code, some concepts related to writing Android apps or progressive apps may be helpful.

Install Android Studio

If you don't already have Android Studio installed in your computer,

click the following link, and follow the instructions on the Android Studio download page.

Download and Install Android Studio

Download the code

Click the following link to download all the code for this codelab, and then unzip the contents into the folder you want to contain your project.

Download source code for the SVGOMG sample

Alternaternatively, clone the GitHub repository:

git clone https://github.com/GoogleChromeLabs/svgomg-twa.git my-sample-twa

Opening the app in Android Studio

Use the shortcut created by the Android Studio installation to start the IDE. The initial screen will look like the following:

Since you will use an existing project as the base for your Trusted Web Activity, select Open an existing Android Studio project, choose the folder containing the source code downloaded in the previous step, and click to open the project.

Modifying the build file to open a different PWA

With the project open, all the configurations you need to change to make it open a different PWA are in a single file: build.gradle.

The gradle file has many configurations, which tells how the Android application is built, including which support libraries to use and Android versions that are supported by the app.

You are going to modify sections of this file that will change the configuration of which PWA will be opened. The relevant section of the file looks like the following:

def twaManifest = [
    applicationId: 'org.chromium.twa.svgomg',
    hostName: 'svgomg.firebaseapp.com', // The domain being opened in the TWA.
    launchUrl: '/', // The start path for the TWA. Must be relative to the domain.
    name: 'SVGOMG TWA', // The name shown on the Android Launcher.
    themeColor: '#303F9F', // The color used for the status bar.
    backgroundColor: '#bababa', // The color used for the splash screen background.
    enableNotifications: false, // Set to true to enable notification delegation.
    useBrowserOnChromeOS: true, // Set to false if you've added interaction with Android system APIs.
    // Add shortcuts for your app here. Every shortcut must include the following fields:
    // - name: String that will show up in the shortcut.
    // - short_name: Shorter string used if |name| is too long.
    // - url: Absolute path of the URL to launch the app with (e.g '/create').
    // - icon: Name of the resource in the drawable folder to use as an icon.
    shortcuts: [
        // Insert shortcuts here, for example:
        // [name: 'Open SVG', short_name: 'Open', url: '/open', icon: 'splash']
    ]
]

You will change your Trusted Web Activity to open https://airhorner.com/. The following are the fields that you change to achieve this:

applicationId

The applicationId uniquely identifies applications on Android devices and on the Google Play store, and follows the same conventions as Java package names, and we need to assign a new one to our application, in order to avoid conflict with applications that may already exist on the device.

In this codelab, you use com.example.mysampletwa as the ID for the application.

defaultConfig {
    applicationId: 'com.example.mysampletwa'
    ...

hostName

Setting up the correct hostName will allow the Trusted Web Activity to handle links from other applications to the Progressive Web App (PWA).

The value must match the domain where the PWA is hosted. In our example this is: airhorner.com

...
hostName: 'airhorner.com',
...

launchUrl

The launchUrl controls which URL will be opened when the Trusted Web Activity is started. It is possible to append query parameters to the URL, for the purpose of tracking or passing more information to the PWA. We are going to use twa-codelab=1 to identify the traffic source:

...
launchUrl: '/?twa-codelab=1',
...

launcherName

The launcherName setting is used to set the name for the application on the Android Launcher. We are going to use AirHorner.

...
launcherName: 'AirHorner'
...

themeColor

The themeColor attribute must defined using the hexadecimal format, and it defines the color of the status bar when a Custom Tabs is opened from inside the Trusted Activity is open.

This is the analog of theme_color defined in the Web Manifest, and you can use the same value that is used there. In the case of AirHorner, the color is defined as #2196F3:

    themeColor: '#2166F3',

backgroundColor

Finally, backgroundColor defines the background color used for the Splash Screen when opening the Trusted Web Activity.

    backgroundColor: '#2166F3'

Summing it up!

Putting it all together, the relevant section of the build.gradle file should now look like the following:

def twaManifest = [
    applicationId: 'com.example.mysampletwa',
    hostName: 'airhorner.com',
    launchUrl: '/?twa-codelab=1',
    name: 'AirHorner',
    themeColor: '#2166F3',
    backgroundColor: '#2166F3',
    enableNotifications: false,
    useBrowserOnChromeOS: true,
    shortcuts: []
]

Running the application

We are now ready to run the application on a device. Make sure that you have an Android device or emulator with Chrome 72 or above installed.

Ensure that the gradle file is synchronized and hit the button on the Android Studio toolbar or use the Ctrl+R keyboard shortcut to run the application.

Android Studio will ask which device to run the application on. Select the connected device or emulator and click OK.

The Android application is still showing the URL bar at the top. This is expected at this point, and the reason for this is that Digital Asset Links requires a two-way validation, and we have only implemented the validation from the Android application to the site at this point.

In the next section, you learn how to run the Trusted Web Activity in debug mode, so you can test the Android application before setting up Digital Asset Links on our domain.

To enable opening the Trusted Web Activity in full screen, the second part of the Digital Asset Links validation—from the site to the Android application—must be enabled.

Enabling debug-mode Trusted Web Activities

When developing a Trusted Web Activity, it is useful to enable a debug mode in Chrome that enables it to skip the Digital Asset Links validation from the site to the application.

This comes in handy when experimenting with AirHorner, as we don't own the domain, and cannot deploy the necessary files to make the validation.

Enable debugging for in chrome://flags

The first step to enable debugging is to use Chrome to navigate to chrome://flags on the Android device, set Enable command line on non-rooted devices to Enabled, and restart Chrome.

Choosing which domain to debug

The flag enabled on the previous step requires you to tell Chrome which domain is going to be debugged.

The SVGOMG sample contains a command-line tool that can help developers to create the required configuration. From the directory where you downloaded the source code for the codelab, run the following:

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

Run the application again. This time, the URL bar at the top should have disappeared, and the UI will look like the following:

The warning at the bottom of the screen is a reminder that you are using Chrome with a debug parameter enabled.

Congratulations!

You have created an Android application that opens a Trusted Web Activity! In the next section, learn how to prepare the site opening to Trusted Web Activity to open it for full screen in production.

Enabling Digital Asset Links on a site

Using the debug mode allows developers to know if the Android application is set up correctly. In order to use Trusted Web Activities in production, a full validation needs to be implemented.

It won't be possible to implement this step in the sample, as you don't have access to add files to airhorner.com.

The next section explains how you can implement this validation with your own Progressive Web App.

Collecting the information

Being able to deploy a file on the domain being validated is the first requirement to implementing the validation, and the domain name is the first information you need.

The second information you need is the applicationId. This the ID that uniquely identifies an application on an Android device or on the Google Play Store. You already created one when you modified the original demo application.

The last information you need is the signing key that is going to be used to deploy the Android application to production and the SHA-256 Fingerprint associated with it.

With the path to the signing key, and its password, here's how to extract the Fingerprint:

> keytool -list -v \
    -keystore ~/.android/debug.keystore \
    -alias androiddebugkey \
    -keypass android \
    -storepass android | grep SHA256

>     SHA256: BD:92:64:B0:1A:B9:08:08:FC:FE:7F:94:B2...

The information you require is the sequence of hexadecimal bytes after the SHA-256 tag.

Adding the validation file to a site

In order to enable the validation on a site, a JSON file describing the relationship to the Android application must be hosted at ./.well-known/assetlinks.json.

A tool for generating the contents of this file is available on the Google Developers site.

Add the information collected on the previous steps to each respective field. The tool generates the JSON content, similar to the following:

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target" : { "namespace": "android_app", "package_name": "com.example.app",
               "sha256_cert_fingerprints": ["BD:92:64:B0:1A:B9:08:08:FC:FE:7F:94:B2:F8:4D:E3:E5:15:BF:C2:FA:0B:73:B8:5C:88:E0:B7:60:8C:6F:B3"] }
}]

Add the content generated by the tool to a file and serve it from ./.well-known/assetlinks.json, relative to the root of your domain.

After this last step, your application can open a Trusted Web Activity in full screen, without having to enable the debug mode!

Generate an icon for your application

When implementing the Trusted Web Activity, you didn't update the icon for the application. Android Studio provides a tool that helps you to generate a compatible icon from an existing image. Check the documentation for the Image Asset Studio to create your own icon.

Check your Progressive Web App

When opening a Progressive Web App inside a Trusted Web Activity, the PWA must fulfill the criteria for installability and performance, and have a minimum performance of 80, as measured by Lighthouse.

If your site is not yet a PWA or doesn't meet the criteria, make sure to check the online resources for creating great Progressive Web Apps.