Guide to Push Notifications in Trusted Web Activities

How Web Push Operates Inside Trusted Web Activities

One of the most frequent questions developers ask when transitioning a Progressive Web App to the Google Play Store is how push notifications are handled. Many assume that because the application is wrapped for Android, they must abandon their existing web push configuration and implement native Android notification systems written in Java or Kotlin.

This assumption is incorrect. Because a Trusted Web Activity runs on top of the system's browser engine (typically Google Chrome), your application has access to the standard Web Push API, Service Workers, and Notification API. When your application is installed via the Google Play Store, it retains the exact same service worker functionality that manages notifications on the standard mobile web.

The underlying mechanism of a push notification in a TWA relies on three core components: the service worker, a push service such as Firebase Cloud Messaging, and the browser engine. When a user installs your application, the TWA wrapper launches your PWA inside a secure browser instance. The application registers a service worker which listens for background push events.

Comparing Web Push to Native Notifications

To understand how this system operates, it is helpful to compare standard Web Push within a TWA to the native push notification systems used in traditional native applications.

While native notifications have full low-level system access, Web Push provides a more cross-platform architecture that enables you to maintain a single notification backend for your website, iOS web users, and Android app installs.

Setting Up the Web Push Infrastructure

To implement push notifications in your TWA, you must configure a secure messaging pathway. The standard method involves using Voluntary Application Server Identification (VAPID) keys. VAPID keys allow your application server to identify itself to the push service, ensuring that messages are secure and sent by an authorised sender.

Configuring Client Permissions

The first step in your codebase is to request notification permissions from the user. This must be triggered by a user action, such as clicking a button, to comply with modern browser policies and design patterns. You call the standard permission request method in your client-side JavaScript:

Notification.requestPermission().then(permission => { if (permission === 'granted') { console.log('Permission accepted'); } });

Once the user grants permission, you can register your service worker and subscribe to the push service. This subscription process generates a unique endpoint URL and cryptographic keys that your server must store. When you want to send a message, your server signs the payload with your private VAPID key and sends it to the user's specific endpoint URL.

Handling the Push Event in the Service Worker

Your service worker is the script that executes in the background of the user's device, even when the TWA is closed. It must contain an event listener for the push event. When the push service delivers a message, the service worker wakes up and executes this listener.

Below is a typical implementation of a push event listener within a service worker script:

self.addEventListener('push', event => { const data = event.data ? event.data.json() : {}; const title = data.title || 'New Notification'; const options = { body: data.body || 'You have received a new update.', icon: '/images/icon-192x192.png', badge: '/images/badge-72x72.png' }; event.waitUntil(self.registration.showNotification(title, options)); });

The event.waitUntil method is crucial. It tells the browser engine to keep the service worker active until the notification has been successfully displayed on the screen. Failing to use this method can lead to the browser terminating the service worker prematurely, resulting in notifications failing to show up reliably.

Addressing OS-Level Challenges and Battery Optimisation

While Web Push inside a TWA is highly reliable, Android's strict battery optimisation rules can introduce challenges. Modern versions of Android proactively limit background processing to conserve battery life. If your user does not open your application for an extended period, the operating system may put the hosting browser engine to sleep, which can delay the delivery of web push notifications.

To ensure high delivery rates, developers must focus on application engagement. Encouraging users to interact with your application regularly signals to the Android system that your app's background tasks should remain prioritised. Furthermore, ensure that your service worker code is clean, free of long-running synchronous loops, and terminates as soon as the notification is rendered.

Managing System Notification Permissions

Another critical detail for TWA developers is how permissions map between the web and native environments. When a user runs your app inside a Trusted Web Activity, they are interacting with your web origin. The browser engine checks the permission state of that web origin to determine if notifications can be shown.

For a seamless user experience, modern Android versions automatically delegate notification permission settings. If a user grants notification permissions to your installed Play Store application during the initial setup or via Android system settings, this permission state is automatically synced to the underlying browser engine. This ensures that users do not face duplicate permission prompts when using your application, keeping the installation flow professional and smooth.