How to Set Up Google Assistant App Actions in a TWA

Voice-Enabled Experiences in Web-to-App Wrappers

Voice interactions are an increasingly popular way for users to engage with mobile applications. Google Assistant allows users to launch apps, trigger workflows, and query content using spoken commands. For developers deploying progressive web apps on Android via a Trusted Web Activity, implementing these voice actions is highly feasible.

By pairing the Android App Actions framework with deep linking, you can configure Google Assistant to launch your TWA directly into specific URLs with custom query parameters. This tutorial guides you through configuring App Actions using standard Android resource configurations and mapping those intents directly to your web application endpoints.

Understanding the App Actions Architecture in TWAs

Google Assistant relies on App Actions to bridge user voice commands with native Android intents. When a user says a phrase like "Hey Google, search for hiking boots on ShopApp," Google Assistant parses the statement and identifies the corresponding intent, such as searching for a product.

In a standard native app, this intent is resolved to a specific native Activity. In a TWA app, we route this intent through Android App Links. Because your TWA validates ownership of your web domain using Digital Asset Links, your application is registered as the default handler for your domain URLs. By mapping voice commands to specific URLs within your domain, Google Assistant launches your TWA wrapper and passes the voice query parameters directly to your web server or service worker.

Step 1: Declare App Actions in the Shortcuts File

Modern Android development handles App Actions through a shortcuts definition file. This file contains the capabilities and parameters that your app supports. To begin, you must create this XML configuration inside your Android project resources.

Create a file named shortcuts.xml in your app's res/xml/ directory. Inside this file, define a capability that corresponds to a standard built-in intent. For example, to support searching, you can declare the standard search intent capability as demonstrated below.

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android"> <capability android:name="actions.intent.GET_THING"> <intent android:action="android.intent.action.VIEW" android:targetPackage="your.package.name" android:targetClass="your.package.name.MainActivity"> <parameter android:name="thing.name" android:key="query"/> <url-template android:value="https://example.com/search?q={query}"/> </intent> </capability> </shortcuts>

In this definition, replacing example.com with your verified PWA domain ensures that Google Assistant routes the query. The parameter element extracts the voice search query, binds it to the placeholder key, and constructs the destination URL.

Step 2: Update the Android Manifest

Once you have configured the capabilities in shortcuts.xml, you must register this file inside your Android Manifest so the operating system can index your voice actions during installation. Open your AndroidManifest.xml file and locate your primary activity block.

Add a meta-data tag inside your launch activity declaration, pointing to the shortcuts XML resource. This file tells the Google Play services during distribution that your application supports voice intents.

<meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts" />

You must also ensure that your Intent Filters for Android App Links are properly configured within the same Manifest file. If your TWA wrapper does not have a verified, functional deep linking filter for your domain, Google Assistant will attempt to open the web browser instead of routing the user into your full-screen app wrapper.

Step 3: Handle Voice Parameters on Your Web Origin

Once Google Assistant resolves a voice command, it opens your TWA wrapper with the resolved deep link URL. From this point forward, the native wrapper hands off execution to your progressive web application. Your web code must listen for these incoming URL query parameters and dynamically update the interface.

You can use standard JavaScript inside your web app's initialisation scripts to capture these values. This works seamlessly across various front-end frameworks like React, Vue, or vanilla JavaScript.

window.addEventListener("DOMContentLoaded", () => { const params = new URLSearchParams(window.location.search); const searchQuery = params.get("q"); if (searchQuery) { executeVoiceSearch(searchQuery); } }); function executeVoiceSearch(query) { console.log("Searching for:", query); // Insert API call or routing logic here }

This mechanism means that you do not need to write any complex native Java or Kotlin code to process voice parameters. All your presentation logic and search queries remain strictly within your web codebase.

Mapping Standard Intents to PWA Paths

Google offers an array of built-in intents that cover typical user actions. You can map these intents to corresponding paths in your progressive web application. Here is a list of common intents and how they translate to web routes.

Testing Your Voice Integrations

To verify that your Google Assistant actions are mapped correctly, you can use the Google Assistant Plugin inside Android Studio. This tool allows you to simulate voice queries without requiring a live voice-input system during development.

Using the Google Assistant Test Tool

• Install the Google Assistant Plugin from the Plugins marketplace inside Android Studio.
• Open the tool by navigating to Tools, then App Actions, and selecting the Test Tool option.
• Select the capability you wish to test, such as GET_THING, and input a mock text parameter.
• Run the test. The plugin will deploy the application to your connected emulator or physical test device, trigger the intent, and launch your TWA into the exact URL path you defined.

Verifying Digital Asset Links

For App Actions to function in production, your app must pass Google's security checks. Google Assistant will not forward user parameters to deep links unless those links are fully verified using Digital Asset Links. Ensure your assetlinks.json file is correctly deployed at your web origin under .well-known/assetlinks.json.

The package name and the SHA-256 certificate fingerprint in your assetlinks.json file must match the signing key of your Google Play Store application. If you use Google Play App Signing, ensure you upload the fingerprint provided by the Google Play Console rather than your local debugging key.

Conclusion

Integrating Google Assistant App Actions with a Trusted Web Activity allows developers to build high-end native features without leaving their web stack. By configuring capability mappings inside shortcuts.xml and linking them directly to your verified PWA paths, you let Google Assistant parse natural language and route users deep into your application. This voice integration elevates your web app to look, feel, and function like a native product on Android.