Using Play Integrity API in Trusted Web Activities

Security is a primary concern for SaaS founders, fintech companies, and indie developers launching applications on the Google Play Store. While Trusted Web Activities provide a seamless bridge for running a Progressive Web App within an Android wrapper, they do not automatically protect your backend APIs from unauthorised access. Because the code for a web app is public, malicious actors can easily inspect your web endpoints and attempt to mimic your application.

To prevent malicious requests, automated bots, and modified client applications from abusing your servers, Google offers the Play Integrity API. This service helps detect whether your app is running on a genuine Android device, whether the app binary is genuine, and whether it was installed from the Google Play Store. Integrating this verification into your TWA workflow establishes a secure pipeline that validates every client requesting access to your systems.

The Threat Model of Web Apps in Native Shells

In a standard web environment, anyone can open developer tools, inspect outgoing HTTP requests, and duplicate API calls using automated scripts or curl. This exposure increases when your app is packaged as an APK or AAB file and distributed on the Play Store, as users assume the native shell guarantees a higher level of trust.

If a developer converts a PWA to an Android package, they use Digital Asset Links to prove ownership of the domain. While this prevents other developers from wrapping your website in their own apps, it does not stop a hacker from decompiling your native APK, altering the target URL to point to a cloned server, or bypassing security checks entirely. The Play Integrity API mitigates this risk by issuing an encrypted, signed token from the device's native hardware, proving that the request originated from your exact, untampered native app shell.

How Play Integrity Works with TWAs

Implementing Play Integrity in a Trusted Web Activity requires a hybrid architecture. Because the web application itself cannot directly query the local Android operating system for Google Play services, the communication must be routed through the native Java or Kotlin wrapper of your TWA. This creates a secure communication loop.

First, your web frontend requests an integrity token when executing sensitive actions, such as during user authentication, payment processing, or database writes. Next, the native TWA activity intercepts this request using a JavaScript Interface or a Web Message Channel. The native app calls the Google Play Integrity SDK to request an attestation token. Google Play Services evaluates the device integrity and issues an encrypted token. The native app passes this token back to your web app, which attaches it as an HTTP header to your API request. Finally, your backend server decrypts the token using Google API client libraries to verify its validity before executing the transaction.

Implementing Web-to-Native Communication

The native wrapper needs to expose a JavaScript Interface to the PWA. This is done inside the custom activity where your Trusted Web Activity is initialized. By binding a custom interface to your web engine, you can invoke native methods directly from your PWA frontend code.

The following table outlines the architectural steps and components required to handle a Play Integrity token loop successfully.

Configuring the Native Token Request

On the native Android side, you will need to import the Play Integrity library inside your native build dependencies. Once imported, you can define a method that requests a token based on a unique nonce generated by your backend server. A nonce is essential to prevent replay attacks where old, valid tokens are intercepted and re-sent.

The native method uses the IntegrityManagerFactory to request an integrity token. The nonce must be formatted as a base64 encoded string. Once the task succeeds, the native code calls back to your web application by executing a custom JavaScript function in the context of the active TWA window.

Validating the Integrity Token on Your Backend

Once your backend server receives the token forwarded by your PWA frontend, it must verify the authenticity of the token before trusting the client's request. There are two primary methods for validating the token: performing decryption locally using your own private key, or sending the token to Google's verification servers via the Play Integrity API endpoint.

The decrypted JSON payload returned by Google contains vital security parameters that you must inspect on your server:

• appLicensingVerdict: Confirms if the user has a valid license, meaning they downloaded your app from Google Play.
• deviceRecognitionVerdict: Indicates whether the device is running a certified version of Android or if it is an emulator, a rooted device, or a system showing signs of tampering.
• packageName: Must match your exact Android package name. If the package name differs, it indicates that someone has unpacked, modified, and re-compiled your application.
• certificateSha256Digest: Validates the signing key used to sign the APK. This prevents attacks where developers sign your code with their own debugging or release certificates.

Best Practices for Implementing Play Integrity in TWAs

Integrating a security API can impact application performance if not designed correctly. First, do not block your app's main thread while waiting for integrity checks. Fetching a token relies on Google Play Services and network activity, which can take several seconds depending on device speed and connection latency. Implement a visual loader on your web app to provide feedback during critical actions.

Second, avoid calling the Play Integrity API for every standard API request. Doing so will result in rate-limiting from Google's servers. Instead, use it only for high-value events, such as initial user login, profile creations, financial transactions, or heavy resource allocations. Once validated, issue a standard, short-lived JSON Web Token (JWT) from your own backend server to manage session authorization for subsequent standard API requests.

By implementing this native-to-web security architecture, you protect your TWA against malicious repackaging and automated API abuse, securing your platform while leveraging the speed and versatility of a Progressive Web App.