Customising Web Push Channels and Sounds in Android TWAs

When developers transition a Progressive Web App (PWA) into an Android app using a Trusted Web Activity (TWA), push notifications are often the first feature they implement to drive user retention. However, many developers soon realise that standard Web Push notifications inside a TWA lack the native touch: they often display under a generic browser-managed channel, play the default system sound, and offer little control over custom vibration patterns or priority levels.

By default, Android groups notifications into functional categories called Notification Channels. Because a TWA is backed by the browser (such as Chrome), push notifications can default to the browser's channel settings instead of your branded application channels. This guide explores how to override these defaults to configure native Android notification channels, assign custom notification sounds, and control vibration patterns within your converted TWA app.

Understanding Web Push Delegation in TWAs

In a standard web environment, the browser manages push notifications. When a user installs your TWA, Android uses a mechanism called WebAPK or delegation. The operating system registers your TWA as the owner of the push subscription. When a push message is received, the Android system routes the payload directly to your installed app package instead of showing a generic Chrome notification.

This routing allows your app to hook into native Android APIs, including Notification Channels. If your application does not explicitly define these channels inside its native configuration and its web service worker, Android fallback mechanics will categorise all incoming alerts under a generic fallback channel, such as Web Notifications or Miscellaneous. This prevents you from offering users granular opt-out controls for different notification types, like marketing updates versus transactional receipt alerts.

Defining Android Notification Channels in the Wrapper

To support custom notification channels and sounds, you must configure your native Android wrapper app. This is done by adding metadata and resource files before compiling your final Android App Bundle (AAB).

First, custom sounds must be placed in the native Android resources. This requires adding your audio files (such as MP3 or OGG formats) to the native resource directory. The files must be saved using lowercase alphanumeric characters and underscores only. The target directory inside your Android project is:

res/raw/custom_notification_sound.mp3

Next, you must declare your default notification channel settings in your Android Manifest file. This ensures that even if a payload does not specify a channel, a fallback with your preferred branding and sound is used. You define this with specific metadata keys within the application block of your manifest:

<meta-data android:name="com.google.firebase.messaging.default_notification_channel_id" android:value="transactional_channel" />

Mapping Web Push Payloads to Native Channels

Once your native wrapper is aware of the available resources, you must match them with the payloads sent from your web application server. This is handled inside your PWA's Service Worker using the showNotification API. The modern Web Push standard allows you to specify metadata that the underlying Android integration interprets to select the correct native channel.

To configure distinct categories of alerts, you should specify the channel ID inside the custom data object of the Push API payload. Android devices running your TWA look for a matching channel ID. Here is an example of the configuration object structure inside your Service Worker's push event listener:

self.addEventListener('push', function(event) { const payload = event.data.json(); const options = { body: payload.body, icon: '/icons/icon-192x192.png', badge: '/icons/badge-72x72.png', vibrate: [200, 100, 200], data: { channelId: 'transactional_channel' } }; event.waitUntil(self.registration.showNotification(payload.title, options)); });

In this block, the channelId property within the nested data object acts as the bridge. If the native wrapper detects an active channel matching that identifier, it applies the associated native settings, such as the custom sound file and importance level.

Configuring Sounds and Vibration Patterns

For custom sounds to trigger correctly on modern Android devices, the sound must be associated with the channel during the channel's creation. Android limits modification of channel properties after creation to prevent apps from changing user preferences. Therefore, the channel must be registered with the correct audio path before the notification is shown.

The table below highlights how the Web Push API options translate directly to native Android notification properties within your TWA:

To ensure custom sounds work reliably, the audio file format should be highly compatible. Using .ogg or .mp3 is recommended. Avoid high-bitrate files to minimise the final size of your compiled APK or AAB wrapper.

Handling Android Channel Importance Levels

Android categorises notifications into importance levels. These determine whether the notification makes sound, vibrates, appears visually as a heads-up banner, or remains silently in the notification tray. When registering channels inside your native TWA wrapper, you can map them to the following priorities:

• High / Urgent: Makes a sound and appears as a heads-up notification banner. Use this for real-time messages, delivery alerts, or urgent alerts.
• Default: Makes a sound and appears in the status bar, but does not interrupt the user with a banner.
• Low: No sound, appears in the tray silently. Perfect for background sync status, non-urgent summaries, or persistent status bars.

By defining these categories native-side and calling them via your Web Push data.channelId parameters, your PWA behaves as an organic native application, respects user system preferences, and avoids the common pitfall of having all notifications muted because a user wanted to disable only one type of alert.