Android Launch Modes for Trusted Web Activities

When a user interacts with an app on Android, they expect navigation to feel natural and predictable. For Progressive Web Apps (PWAs) operating inside a Trusted Web Activity (TWA), managing this flow requires a solid understanding of Android Launch Modes. Without correct configuration, actions like tapping a push notification or clicking a deep link can result in multiple, duplicate instances of your web app running simultaneously.

Android handles application routing through a system of Tasks and Back Stacks. By understanding how to configure the launchMode attribute within your application manifest, you can control whether your PWA launches in a new window, reuses an existing running instance, or intercepts incoming intents to maintain a single, cohesive user session.

What are Android Launch Modes?

A Launch Mode is an instruction to the Android operating system detailing how a specific Activity (in this case, the TWA wrapper enclosing your PWA) should be opened. By default, Android uses a stack-based system. Each time an application activity is called, a new instance is created and pushed onto the top of the history stack, regardless of whether that activity is already running.

For traditional native applications with many distinct screens, this stack model is standard. However, for a PWA, your entire application typically runs within a single instance of Chrome or another Custom Tabs provider. Creating multiple instances of this activity wastes system memory and leads to a fragmented user experience, where pressing the back button multiple times simply cycles through duplicate states of the same web app.

Comparing Launch Modes for TWA Integration

Android provides four primary launch modes. Selecting the correct one determines how your web application responds to system launch intents.

Why singleTask is Best for Most PWAs

For almost all converted PWAs, singleTask is the optimal launch mode configuration. When an activity is configured as singleTask, the Android system treats it as a unique singleton within the task hierarchy.

If the user taps your app icon while the app is closed, Android creates a new task and opens your PWA. If the user subsequently navigates away (for example, to check their email) and then taps your app icon again, Android does not launch a new instance of your PWA. Instead, it pulls the existing task back to the foreground, preserving the exact state, scroll position, and active session of your web application.

This behavior is identical to how native platforms handle apps like Spotify or Twitter. It prevents the system from spinning up multiple browser rendering contexts, conserving device battery and processor overhead.

Configuring the Launch Mode in Your Build

To set the launch mode, the configuration must be declared inside the AndroidManifest.xml file of your wrapper application. Within the activity element representing your Trusted Web Activity, you define the launchMode attribute.

For developers using automation or configuration tools to build their TWA, this setting is usually pre-configured to singleTask or singleTop. If you are manually maintaining or customizing your Android wrapper code, ensure your activity definition resembles the following structure:

<activity android:name="com.google.android.keynote.TwaLauncherActivity" android:launchMode="singleTask">

This declaration ensures that any external launch trigger targets the single, primary activity instance.

Handling New Intents and Deep Links

Using singleTask introduces a technical challenge: how does your app receive new data when it is already open? If a user clicks a deep link targeting your PWA (such as https://example.com/product/123) while the app is running in the background, Android brings the existing instance to the foreground rather than creating a new one with the target URL.

In a native application, this scenario is handled by the onNewIntent method within the Android Activity lifecycle. When the system redirects a user to an already-running activity, it bypasses the standard onCreate lifecycle stage and sends the new intent data (the target URL) straight to onNewIntent.

For a TWA, the underlying wrapper handles this handoff automatically. When a new deep link intent is received, the TWA wrapper detects the updated URL parameters and instructs the underlying web engine to navigate directly to the new path. To ensure this works flawlessly, your Web App Manifest and your Digital Asset Links must be correctly configured to validate ownership of the target domain, allowing the system to route those links directly into your existing app instance without browser safety warnings.

The Impact of launchMode on Web Sessions and State

Using the incorrect launch mode can disrupt your web-level state management, including session cookies, LocalStorage, and IndexedDB data. While Chrome shares storage across instances, having multiple instances of your PWA open concurrently can lead to race conditions. For example, if Instance A writes to LocalStorage while Instance B is modifying the same key, your application state can become corrupted.

By enforcing a singleTask architecture, you guarantee that only one interface of your PWA is active at any given moment. This simplifies your service worker strategies, keeps your state predictable, and matches the natural expectation of mobile device users.