How to show a notification banner on Android (Heads-up notifications)

Question: I want a received push notification to appear as a banner at the top of the screen, instead of only showing up in the notification drawer and as an icon in the tray.

Answer: Notifications are rendered by the Android OS. The Pushwoosh SDK only hands the notification object to the system, so the SDK cannot force a banner — it can only tell Android that the notification is important enough to be shown as a heads-up notification.

A heads-up notification briefly appears in a floating window over the current app. Per Google's documentation, it is triggered when:

• the notification channel has high importance (Android 8.0 / API 26 and later — this is the case for virtually all devices in use today);
• the user's activity is in fullscreen mode and the app uses fullScreenIntent;
• (legacy, Android 7.1 / API 25 and earlier) the notification has high priority and uses a ringtone or vibration.

The device must also be unlocked — on a locked screen the notification is shown on the lock screen instead.

How to request a heads-up from Pushwoosh

1. Send to a high-importance channel. Add {"pw_channel":"anytext"} to android_root_params in your /createMessage request or in the Control Panel. Pushwoosh creates the channel with high importance on first use.
2. Set high priority via the android_priority API parameter (or the Priority control in the Control Panel). This is what still matters on Android 7.1 and older, and it is harmless on newer versions.

Important limitations

• Android 13 (API 33) and later: your app must request the POST_NOTIFICATIONS runtime permission and the user must grant it. Without it no notification is displayed at all.
• A channel's importance is fixed once created. If a channel was first created with default importance, changing it later in code has no effect — the user must change it in system settings, or you must use a new channel ID.
• The user can downgrade or silence any channel in Android system settings, and the OS may suppress heads-up notifications under Do Not Disturb, in Focus modes, or when the same channel posts too frequently.