How to Detect Sideloading and Verify Origin in Android TWAs

When you wrap a Progressive Web App (PWA) using a Trusted Web Activity (TWA) and publish it, your web content is rendered inside an optimized, secure system container. However, because Android allows users to download and install application packages (APKs) outside of official marketplaces, developers often face security challenges. Unauthorised third parties can download your signed APK, extract or decompile it, repackage it under a different name, or side-load it onto devices. This article explains how to determine if your application was installed through the official Google Play Store or if it was sideloaded.

The Security Risks of TWA Sideloading

Sideloading presents security challenges for both web-focused companies and indie developers. When an application is sideloaded or repackaged, several vulnerabilities can occur. First, malicious actors can build a custom application wrapper targeting your web application's public URL, trying to trick users into believing they are using an official, secure client. Second, users sideloading old or modified versions of your application bypass updating channels, which can disrupt application telemetry, crash reporting, and analytical pipelines.

Because the core of your software runs as standard web resources, verifying the execution environment is crucial. By knowing whether your code runs inside a certified web browser, an authorized Google Play installation, or an untrusted sideloaded application package, you can toggle functional access, restrict premium capabilities, and protect sensitive resources.

How Digital Asset Links Protect Your Origin

The primary mechanism for verification in Trusted Web Activities is Digital Asset Links. This association relies on a JSON file located at your domain's .well-known/assetlinks.json path. The file contains the exact package name of your Android application and the SHA-256 fingerprint of your application's signing certificate.

When a user opens your application, the operating system checks if the signing key of the installed APK matches the certificate published at your web domain. If they match, the browser removes the URL bar, establishing a secure, full-screen native user interface. If a malicious actor attempts to sideload your APK with a modified package name, or compile their own APK pointing to your domain, the validation checks will fail. Consequently, the user will see a standard browser navigation bar, signaling that the app is running in an unverified state.

While this browser UI change warns users of an unverified origin, your web application's client-side code must also detect this state to protect business logic, process payments securely, or lock down API access.

Verifying the App Installer Source in Android

To explicitly detect where the application wrapper was installed, you can query the Android system APIs within the native portion of your TWA wrapper. The Android platform tracks which application or system process installed a given package. Developers can access this information using the PackageManager system class.

Within the native Android code of your custom TWA launcher activity, you can request the installer package name. For devices running modern Android releases, the recommended approach is querying getInstallSourceInfo, while legacy devices use the getInstallerPackageName helper. Below is an implementation illustrating how this data can be retrieved:

PackageManager pm = context.getPackageManager(); String installer = pm.getInstallerPackageName(context.getPackageName()); if (installer == null) { // Installed via ADB sideload, local file manager, or manual APK install } else if (installer.equals("com.android.vending")) { // Installed from the official Google Play Store } else if (installer.equals("com.amazon.venezia")) { // Installed from the Amazon Appstore }

Passing the Installation Source to Your Web App

Once the native wrapper identifies the installer source, this configuration state must be communicated to your web-based runtime environment. The most reliable and secure way to share this installation metadata during boot is by appending a unique parameter to the start URL when the TWA launches.

Inside your native Android application configuration class, modify the launch URL parameter dynamically before firing the intent that opens the TWA. Below is an example of adjusting the launch configuration to include the verified installer context:

String startUrl = "https://example.com/index.html"; String installer = pm.getInstallerPackageName(context.getPackageName()); if (installer == null) { installer = "unverified_sideload"; } String secureLaunchUrl = startUrl + "?origin_source=" + URLEncoder.encode(installer, "UTF-8"); // Provide secureLaunchUrl to your TWA Builder setup

When your web application loads, your client-side scripts can read the query parameter to verify the execution source and cache this state in browser-secure session storage. Developers should use caution, as query parameters can theoretically be spoofed in standard browser environments. For elevated security, couple this with an validation handshake where the web server checks browser signatures, or restrict highly sensitive actions to environments where Digital Asset Links has verified the origin.

Handling Unverified App Installations

When your application detects that it has been sideloaded, your system should react based on your business risk tolerances. The table below lists the common installation sources on Android and the standard handling patterns developers should implement:

For applications handling high-value digital goods, complete verification ensures your infrastructure remains protected against reverse-engineering and unofficial distribution, while maintaining a smooth path for users on trusted, verified devices.