Trusted Web Activity

How to validate your web app - and create an Android app from it

Do you trust me?

For some time now web applications could be transformed to a native app with little effort, depending on the app’s complexity. For instance, frameworks like Capacitor.js or Cordova offer such functionality and are also open source software. To offer a web app as a native one, you have to build the web application locally, tell the framework where this build output is located and basically wait until the apps get created. The core concept is that your website just runs in an embedded webview. Well, things are about to change now once again by introducing “Trusted Web Activity” by Google.


What is “Trusted Web Activity” (TWA)? Here’s the gist:

  • A “Trusted Web Activity” is used in the context of Google Play Store and a native Android app generated from a PWA
  • You can verify ownership of your PWA for the Android app by creating a credential called “assetlinks” - this is where Google Play is needed
  • by uploading this “assetlinks”-file to your web app’s public directory, Google can verify ownership of the PWA when the native Android app gets so no one but you can create it

Alright, this was a brief overview of the concept behind TWA. To recap, the “trust” part relates to the verification of ownership of your PWA.

One new TWA, please!

Ok, but how does it actually work? The setup is actually really simple and shouldn’t take more than an hour. Here’s how it’s done:

First, make sure your PWA is set up correctly:

  • manifest.json is available and validated
  • icon + name are correct
  • you can check these changes quickly in DevTools

The main library that will take all of the heavy lifting is called “bubblewrap”, a Node.js package that delivers a CLI, which will use throughout the tutorial.

First, create a new directory for the TWA called “twa”. Inside of “twa” we’ll create one more directory called “android”. “twa” itself will contain the node_modules and “android” the actual native Android app.

Make sure you’re now inside of “twa” to init a new npm project:

npm init -y

Now let’s add the CLI as a dev dependency:

npm i -D @bubblewrap/cli

That’s all we need for now. Let’s init the “bubblewrap”-project then. Just replace the domain with yours and check where the “manifest.json” is located. You’ll be asked for the Java SDK + Android SDK locations, which you can reuse if they’re already installed:

npx bubblewrap init --manifest=

Moving on, it’s time to go through some questions and answers with the “bubblewrap” CLI. Depending on the available metadata in your PWA, most of the fields will be already prefilled:

npx bubblewrap build

Now that your PWA has been identified and the Android app is created, it’s time for a quick smoke test. Either start an emulator or use your testing real device of choice:

npx bubblewrap install

If everything works out fine, you’ll see your web app as a working native Android app. Great, the hardest part is already done!

What’s left is the creation of the verification-file called “assetlinks.json”. As I’m assuming you want to upload the app bundle to Google Play, it’s important to note how the signing is actually managed:

  • Google Play will manage the signing keys for you, which means we have to look up the corresponding SHA-256 value in Google Play Console
  • “bubblewrap” might have created an “assetlinks”-file already with one entry, which contains a different SHA-256 hash - no worries, we’ll use both keys from Google Play and the generated one

If no “assetlinks” file has been created, the way I proceeded was to download “Asset Links Tool” (recommended by Google, link in addendum) on my testing device and read out the SHA-256 from the installed signed testing app created and installed by “bubblewrap”. This json can then be used by you. Just make sure to duplicate the first entry and replace the SHA-256 with the one from Google Play, resulting in an “assetlinks” file with 2 entries, differing only in their signing keys.

Almost done, you now just have to create a new directory in your existing PWA’s public folder and upload the app once:


Now Google can read it and verify ownership.

One… more… step...

All that’s now left is to upload the release-bundle to Google Play and release it! Yes, it’s actually that simple. Google really pushes what’s possible on the web and isn’t afraid to try out new things. “Trusted Web Activity” is one new way to bridge the gap between web and native even further, although currently limited to Android.

Oh, and yes: of course this web app is a PWA and a TWA. You can check out the Android app in Google Play, link is below in the addendum.

  • Tom