Requesting Android 13 Notification Permissions in a TWA

The Impact of Android 13 on Web Push Notifications

Historically, Android applications could post notifications to the system tray without requiring explicit runtime permission from the user. Users had to manually opt out via settings if they wished to silence an app. However, starting with Android 13 (API level 33), Google introduced a strict runtime permission model for notifications. Apps must now explicitly ask the user for permission before they can send any alerts.

For developers running Progressive Web Apps inside a Trusted Web Activity (TWA), this change introduces a unique technical challenge. While a web browser handles its own permission prompts for standard website visitors, a TWA packaged as a native Android app operates under the native permissions of its host container. If your native Android wrapper app does not request and receive permission from the user, the underlying Chrome Custom Tabs engine cannot trigger push notifications, and your web-based calls to request notifications will fail silently.

How TWA Notification Permission Flow Works

When you convert a PWA into an Android app using a TWA, the communication of notification state must traverse multiple layers. The state flow behaves differently depending on how permissions are handled on the native side versus the web side.

If your native app does not request the permission, calling the standard JavaScript notification api on your web page will return a denied status instantly, without giving the user a chance to opt in. To fix this, you must declare and request the permission natively.

Step 1: Declaring the Permission in the Android Manifest

The first step in resolving this blocker is to declare that your application uses notifications. This declaration must exist inside your project's primary Android manifest file.

Open your native project source and find the file located at the following path:

app/src/main/AndroidManifest.xml

Inside the manifest element, but outside of the application element, add the following uses-permission line to declare the required permission:

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

By declaring this, you inform the Android operating system that your app has the capability to send push notifications, allowing the OS to grant the request when prompted.

Step 2: Handling the Permission Request in the Launcher Activity

Declaring the permission in the manifest is necessary, but it does not trigger the prompt on Android 13+ devices. You must programmatically request this permission at runtime. The ideal place to request this is inside your main native Activity, before the TWA intent launches, or through an initial onboarding process.

If you are writing or customizing the launcher code in Java, you must check the system API level first. If the device is running API level 33 or higher, check if the permission has already been granted. If it is not, trigger the system dialog.

Here is how to check and request this permission inside your activity's lifecycle:

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {

if (ContextCompat.checkSelfPermission(this, Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED) {

ActivityCompat.requestPermissions(this, new String[]{Manifest.permission.POST_NOTIFICATIONS}, 101);

}

}

This block of code ensures that users on Android 13 and above are presented with the native opt-in dialog immediately when they launch your application for the first time. Once granted, Chrome Custom Tabs inherits this native permission state.

Best Practices for the Push Notification User Experience

While popping a native permission dialog immediately on launch is technically effective, it can lead to low opt-in rates if users do not yet understand the value of your application. To optimize conversion, consider implementing a progressive disclosure strategy.

• Use an Onboarding Screen: Explain the benefits of enabling notifications (such as receiving order updates, messaging alerts, or real-time tasks) before launching the native prompt.
• Graceful Degradation: If the user denies the native permission, design your PWA to fall back gracefully to in-app notification centres, email alerts, or SMS.
• Status Verification: Before calling your web push subscription routines in your JavaScript service worker, check the permissions API state in your frontend code to ensure everything is synchronised.