Display time-sensitive notifications

Your app might need to get the user's attention urgently in certain situations, such as an ongoing alarm or an incoming call. On devices that run Android 9 (API level 28) or lower, you might handle this by launching an activity while the app is in the background. This document shows how to achieve this behavior on devices running Android 10 (API level 29) (API level 29) and higher.

Add the POST_NOTIFICATIONS permission

Starting in Android 13 (API level 33), declare the POST_NOTIFICATIONS permission in your AndroidManifest.xml file:

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

After you declare the permission, create a notification channel.

Create a notification channel

Create a notification channel to display notifications and let users manage notification categories in system settings. For more information about notification channels, see Create and manage notification channels.

Create your notification channels in the onCreate method of your Application class:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        val channel = NotificationChannel(
            CHANNEL_ID,
            "High priority notifications",
            NotificationManager.IMPORTANCE_HIGH
        )

        val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        notificationManager.createNotificationChannel(channel)
    }
}

When the user runs the app for the first time, the system displays the channel in the App info screen, as shown in Figure 1:

The App Info notification screen displaying the created channel.
Figure 1. Notifications section in the App Info screen of the app's system settings.

Manage notifications permissions

Starting in Android 13, request notification permissions before you show notifications to users.

The following code example shows how to request runtime notification permission in Jetpack Compose:

val permissionLauncher = rememberLauncherForActivityResult(
    contract = ActivityResultContracts.RequestPermission(),
    onResult = { hasNotificationPermission = it }
)
// ...
Button(
    onClick = {
        if (!hasNotificationPermission) {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
                permissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
            }
        }
    },
) {
    Text(text = "Request permission")
}

On devices that run Android 13 and higher, tapping the Request permission button displays the system dialog shown in Figure 2:

The system dialog prompting the user to allow notifications.
Figure 2. System dialog for the notification permission request.

When the user grants the permission, the system updates the App info screen, as shown in Figure 3:

The App Info screen showing notification permissions granted.
Figure 3. Notification permissions granted.

Create a high-priority notification

When you build a high-priority notification, provide a clear title and message text. Also assign a high-importance channel and priority level.

The following code example configures and builds a high-priority notification:

private fun showNotification() {
    val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager

    val notificationBuilder =
        NotificationCompat.Builder(this, CHANNEL_ID)
            .setSmallIcon(R.drawable.baseline_auto_awesome_24)
            .setContentTitle("HIGH PRIORITY")
            .setContentText("Check this dog puppy video NOW!")
            .setPriority(NotificationCompat.PRIORITY_HIGH)
            .setCategory(NotificationCompat.CATEGORY_RECOMMENDATION)

    notificationManager.notify(0, notificationBuilder.build())
}

Display the notification to the user

Calling the showNotification function triggers the notification as follows:

Button(onClick = { showNotification() }) {
    Text(text = "Show notification")
}

Figure 4 shows the high-priority notification displayed by the system:

A high-priority notification displayed on the device.
Figure 4. A high-priority notification.

Ongoing notification

When you display your notification to the user, they can acknowledge or dismiss your app's alert or reminder. For example, the user can accept or reject an incoming phone call.

If your notification represents an ongoing background task, such as an active phone call, associate the notification with a foreground service. The following code snippet shows how to display a notification associated with a foreground service:

// Provide a unique integer for the "notificationId" of each notification.
startForeground(notificationId, notification)

Consider using Live Updates

Time-sensitive ongoing notifications can benefit from increased visibility. Consider promoting ongoing notifications as Live Updates to display status information across system UI surfaces.