How Push Notifications Work in a Trusted Web Activity

Understanding how push notifications work in a Trusted Web Activity (TWA) is one of the most common hurdles web developers face when publishing their Progressive Web App (PWA) to the Google Play Store. When you convert a web application into an Android package, you are wrapping a web experience inside a native container. However, unlike traditional hybrid apps that rely on complex native plugins, a TWA handles push notifications using the standard Web Push API.

This architecture simplifies development because you do not need to maintain separate notification infrastructure for your website and your Android application. The same push service worker that sends notifications to desktop Chrome or mobile Safari also delivers alerts to your users inside the installed Android app. This article details the technical mechanics, configuration steps, and security workflows required to run push notifications seamlessly within a TWA.

How TWA Push Notifications Work under the Hood

A Trusted Web Activity is powered by Chrome Custom Tabs, which means the underlying rendering engine is the user system browser. When a user installs your TWA on Android, they are installing a lightweight wrapper that points to your web origin. Because the app runs directly on the system browser engine, it shares the same cookie jar, local storage, and service worker registration as the standard mobile browser.

When you trigger a push notification, the request goes through the Web Push Protocol to a push service, such as Google Cloud Messaging (GCM) or Firebase Cloud Messaging (FCM) acting as the web push intermediary. The Android operating system keeps a persistent connection to these services. When a push payload arrives, the OS wakes up the browser engine, which in turn invokes your service worker background push event listener. This process works even if your application is closed or the device screen is locked.

Web Push vs Native Firebase Push

Many developers assume they must integrate the native Android Firebase SDK to receive notifications inside an Android app. When using a TWA, this is not necessary. Instead, you use the standard Web Push standard, which requires Voluntary Application Server Identification (VAPID) keys.

As shown in the table, Web Push is significantly simpler to manage. By utilising the unified web codebase, your notifications work across mobile web, desktop web, and your installed Google Play store application simultaneously.

Implementing the Push Service Worker

To receive push notifications inside your TWA, you must have a registered service worker with a functional push event listener. The service worker operates in the background, listening for the push event broadcasted by the operating system.

First, you must register your service worker in your main application JavaScript file. You should check if the browser supports service workers and push messaging before attempting registration:

if ('serviceWorker' in navigator && 'PushManager' in window) { navigator.serviceWorker.register('/service-worker.js'); }

Once registered, you must implement the push event handler inside the service-worker.js file. This handler intercepts incoming payloads, extracts the title, body, and icon, and displays the system-level alert using the notification manager:

self.addEventListener('push', function(event) { if (event.data) { const payload = event.data.json(); const options = { body: payload.body, icon: payload.icon || '/icon-192.png', badge: payload.badge || '/badge.png', data: { url: payload.url } }; event.waitUntil(self.registration.showNotification(payload.title, options)); } });

In this code block, the event.waitUntil method tells the operating system not to terminate the service worker thread until the browser has successfully rendered the notification. This ensures high delivery reliability, especially on resource-constrained Android devices.

Permission Delegation in Android

Before Chrome 84, requesting notification permissions inside an installed TWA was a disjointed experience. Users would see a browser-style permission prompt inside a native app shell, which hurt trust and reduced conversion rates. Modern Android versions resolve this using notification permission delegation.

When your web application calls Notification.requestPermission() inside the TWA wrapper, the system automatically translates this into a native Android runtime permission dialog. If the user grants permission inside the app, the decision is immediately synced with the underlying web browser settings. This native delegation is only active if your application has verified its identity using Digital Asset Links. If the Digital Asset Links relationship is not verified, the app will fall back to showing standard browser-style prompts, or block permissions entirely in strict environments.

Troubleshooting Notifications in Production

If push notifications fail to arrive inside your TWA after publishing to Google Play, the issue is almost always related to asset link verification or system battery optimizations. First, verify that your service worker scope covers the URL that your TWA launches. If your launcher activity points to https://example.com/app/ but your service worker is registered at https://example.com/app/assets/, the service worker will not control the launch page, and push subscription events will fail.

Second, check the Android system-level battery optimization settings. Android aggressively puts idle apps to sleep to conserve power. While native applications have mechanisms to request high-priority wake locks, TWA notifications rely on Chrome background process handling. To guarantee delivery, ensure that your push server transmits the notification payload with a high urgency setting, which instructs the Android system to wake up the browser background worker immediately. Finally, verify that your production Digital Asset Links file contains the correct SHA-256 fingerprint matching your active Google Play App Signing certificate, ensuring that permission delegation works seamlessly across all active user devices.