Package Visibility in Android TWAs: Manifest Queries

When Android 11 (API Level 30) was released, Google introduced a major security update known as package visibility. This change limited how apps query and interact with other installed apps on a user device. For developers of Trusted Web Activities (TWAs), package visibility is a critical concept. If your web app interacts with external apps, handles specific custom protocols, or relies on system browsers, you must configure your Android manifest correctly to prevent broken user journeys.

Understanding Android Package Visibility

Prior to Android 11, any app installed on an Android device could query the package manager to retrieve a complete list of other installed apps. This presented a privacy concern, as malicious apps could use this capability to track user software habits.

Under the package visibility model, an app must explicitly declare which other packages it needs to interact with. If your application attempts to query or launch an external application without the correct declaration, the system will behave as if the target app is not installed, causing intents to fail silently or throw exceptions.

Why Package Visibility Impacts Trusted Web Activities

At its heart, a Trusted Web Activity is a native Android application shell that launches a system browser. Therefore, your TWA relies heavily on external package communications. There are three primary scenarios where your TWA requires package visibility configurations:

• Verifying Chrome or Custom Tabs Providers: The TWA wrapper needs to determine which browsers on the user device support Custom Tabs to choose the best rendering engine.
• Handling Custom Protocols: If your web app includes links using custom URI schemes like mailto, tel, sms, or maps, the TWA must query the system to find an appropriate app to handle these actions.
• Deep Linking and External Authentication: When redirecting users to third-party authentication providers (such as social login apps), your wrapper needs to verify if the corresponding native app is installed to facilitate a smooth handoff.

Declaring Queries in AndroidManifest.xml

To grant your TWA the necessary package visibility, you must add a <queries> element inside the AndroidManifest.xml of your Android wrapper project. This element sits directly inside the root <manifest> element, alongside <application>.

The <queries> element allows you to define visibility requirements in three ways: by package name, by intent signature, or by provider authority. For TWAs, intent signatures are the most common and versatile configuration.

Example: Querying Web Browsers and Custom Tabs

To allow your TWA wrapper to discover installed browsers that support Custom Tabs, you must declare an intent query for web browsing capabilities. Here is the standard manifest configuration:

<queries>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="https" />
    </intent>
</queries>

This declaration ensures your TWA can query the Android Package Manager for any browser that can handle HTTPS URLs, enabling the wrapper to select the optimal Chrome-based browser engine dynamically.

Configuring Common Communication and Media Intents

If your Progressive Web App contains standard web communication buttons, such as phone calls or emails, you must declare these intents explicitly. Without these declarations, your TWA might fail to open the native dialler or email client when a user clicks a link inside your web interface.

To support all of these protocols simultaneously, combine them inside a single <queries> block. Here is a comprehensive example showing how to structure your manifest to allow these external integrations:

<queries>
    <intent>
        <action android:name="android.intent.action.DIAL" />
        <data android:scheme="tel" />
    </intent>
    <intent>
        <action android:name="android.intent.action.SENDTO" />
        <data android:scheme="mailto" />
    </intent>
    <intent>
        <action android:name="android.intent.action.VIEW" />
        <data android:scheme="geo" />
    </intent>
</queries>

Avoid Using the QUERY_ALL_PACKAGES Permission

When searching for a quick fix, some developers discover the android.permission.QUERY_ALL_PACKAGES permission. When added to the manifest, this permission completely bypasses the package visibility restrictions, allowing your app to see every other app on the device.

However, Google Play has incredibly strict policies regarding this permission. It is classified as a highly sensitive permission. Google only permits its use in specific, justified scenarios, such as device search apps, file managers, or antivirus software. If your TWA requests this permission, your app will almost certainly be rejected during the Google Play Store review process. Always use the target-specific <queries> element instead.

Testing Your Package Visibility Implementation

Once you have configured the <queries> element in your TWA wrapper project, it is essential to test your application on an Android device running Android 11 or higher. During testing, pay attention to the following areas:

First, verify that your TWA launches immediately without falling back to a standard browser tab. If the TWA fails to detect custom tab providers due to missing queries, it might fall back to an external browser, which breaks the immersive app experience.

Second, test every external button within your web app. Click your telephone, email, and map links. Ensure the Android operating system prompts you to choose a native handling application immediately without delay or application freezes.

By proactively managing package visibility in your Android TWA manifest, you secure a smooth, bug-free native experience for your users while adhering perfectly to modern Android security standards and Google Play policies.