The system promotes Live Update notifications. Promoted notifications appear
more prominently on system surfaces, including at the top of the notification
drawer and the lock screen, and as a chip in the status bar.
![](https://developer.android.com/static/images/design/ui/mobile/notifications-live-update.png) **Figure 1.** An example of a Live Update notification.

Promoted notification cards have the following appearance characteristics:

- Expanded by default
- Uncollapsible

Your notification must meet the following requirements to qualify as a live
update:

- Must be Standard Style, [`BigTextStyle`](https://developer.android.com/reference/android/app/Notification.BigTextStyle), [`CallStyle`](https://developer.android.com/reference/android/app/Notification.CallStyle), or [`ProgressStyle`](https://developer.android.com/reference/android/app/Notification.ProgressStyle).
- Must request the following non-runtime permission in the android manifest `android.permission.POST_PROMOTED_NOTIFICATIONS`.
- Must request promotion using `EXTRA_REQUEST_PROMOTED_ONGOING` or `NotificationCompat.Builder#requestPromotedOngoing`.
- Must be [`ongoing`](https://developer.android.com/reference/android/app/Notification.Builder#setOngoing(boolean)) (set [`FLAG_ONGOING_EVENT`](https://developer.android.com/reference/android/app/Notification.Builder#setOngoing(boolean)))).
- Must have a `contentTitle` set.
- Must **NOT** have any [`customContentView`](https://developer.android.com/reference/android/app/Notification.Builder#setCustomContentView(android.widget.RemoteViews)) set (no `RemoteViews`).
- Must **NOT** be the summary of a group using [`setGroupSummary`](https://developer.android.com/reference/android/app/Notification.Builder#setGroupSummary(boolean)).
- Must **NOT** [`setColorized`](https://developer.android.com/reference/android/app/Notification.Builder#setColorized(boolean)) to `TRUE`.
- The notification channel must **NOT** have [`IMPORTANCE_MIN`](https://developer.android.com/reference/android/app/NotificationManager#IMPORTANCE_MIN).

## Promotion characteristics

The following APIs help you determine whether the system will promote your
notification:

- `Notification.FLAG_PROMOTED_ONGOING` indicates whether the notification is promoted.
- `Notification.hasPromotableCharacteristics()` validates whether the system can promote the notification. This method does not consider whether the user disabled Live Updates for the app in settings.
- `NotificationManager.canPostPromotedNotifications()` checks whether your app can post a promoted notification, for example, if the user enabled or disabled it in settings.
- `Settings.ACTION_MANAGE_APP_PROMOTED_NOTIFICATIONS` is the intent action that allows apps to send users to Settings to enable this feature.

| **Note:** Original Equipment Manufacturers (OEMs) can enforce additional criteria for Live update eligibility. Check their respective documentation for details.

## Usage criteria

Use Live Updates for activities that are ongoing, user-initiated and time
sensitive.

### Ongoing

A Live Update must represent an activity that is actively in progress, with a
distinct start and end. If an activity occurs in the past, don't use a Live
Update. Instead, use a standard notification. This is also true for events that
have not yet begun, although events that are about to start can use a Live
Update.

Live Updates represent ongoing activities. Don't use Live Updates to offer
accelerated access to app functionality. If you want to do this, use an app
widget or a custom Quick Settings tile.

- **Appropriate uses:** Active navigation, ongoing phone calls, active rideshare tracking, and active food delivery tracking.
- **Inappropriate uses:** Ads, promotions, chat messages, alerts, upcoming calendar events, and quick access to app features.

### User-initiated

Most Live Updates should represent activities that are explicitly triggered by
the user, such as starting a workout, initiating driving navigation, or hailing
a rideshare. Don't show ambient information, such as that about the user's
environment, interests, or upcoming events, in a Live Update. Don't allow
activities triggered by other parties to generate Live Updates.

Sometimes, a user might perform an action that initiates an activity for some
time in the future. For example, if the user purchases tickets for a flight or
concert, signs up for a tournament, or otherwise indicates their future
attendance to a time-sensitive event. In these cases, it may be appropriate to
automatically show a Live Update when the scheduled event begins. However, apps
must tune their triggers to only appear when the activity is imminent. If the
user explicitly indicates that they want to begin monitoring a background event
such as a sports game, you can begin posting Live Updates for that event.
However, you should also include an **Unpin** action in the associated
notification.

### Time Sensitive

Show a Live Update only if it requires the user's attention throughout the
activity. A key use case for Live Updates is monitoring, when the user gets
significant benefit from glancing at the Live Update to keep an eye on the
evolving state of the activity.

A Live Update is often appropriate for activities that transition between Live
Updates and normal notifications. For example, showing a boarding pass
notification is appropriate many hours before a user's flight, but the
notification should become a Live Update only when the user has a pressing need,
such as when they have arrived at the airport or venue or once boarding has
begun. In contrast, a Live Update isn't appropriate for tracking a package as
the user doesn't need to constantly monitor this.

## Status Chips

Status chips allow users to keep track of Live Updates when the notification is
not in view. Use [`setShortCriticalText`](https://developer.android.com/reference/android/app/Notification.Builder#setShortCriticalText(java.lang.String)) or [`setWhen`](https://developer.android.com/reference/android/app/Notification.Builder#setWhen(long)) to convey
important state information regarding your progress centric notification.
![status chip with icon](https://developer.android.com/static/images/ui/notifications/status-chip-1.png) **Figure 2.** Indeterminate state displays the small icon, `Notification.Builder#setSmallIcon`. ![status chip with time](https://developer.android.com/static/images/ui/notifications/status-chip-2.png) **Figure 3.** Use `Notification.Builder#setShortCriticalText` to show absolute time. ![status chip with info](https://developer.android.com/static/images/ui/notifications/status-chip-3.png) **Figure 4.** Use `Notification.Builder#setShortCriticalText` to convey critical information.

### When time

The when time triggers a countdown for the longevity of the notification, unless
the notification is dismissed or updated. The following bullets describe how
when time works in various situations:

- The when time is at least 2 minutes in the future: If the current time is 10:05 am and the when time is set to 10:10 am, then the chip says **5min**.
- The when time is more than 1 minute in the past: The notification isn't shown.
- A timer in the chip can be shown when using Chronometer for when time. See [`setUsesChronometer`](https://developer.android.com/reference/android/app/Notification.Builder#setUsesChronometer(boolean)) and [`setChronometerCountdown`](https://developer.android.com/reference/android/app/Notification.Builder#setChronometerCountDown(boolean)). The Chronometer timer is shown in the chip as long as it is positive.
- You don't want the when time to show on your notification: Use [`setShowWhen`](https://developer.android.com/reference/android/app/Notification.Builder#setShowWhen(boolean)) to `FALSE`.

### Status chip appearance

The status chip always includes an icon, and optionally includes text. The chip
has a maximum width of 96dp. The text will show only if the entire text can fit
in the chip. The text displays depending on the following criteria:

- If less than 7 characters, show the whole text.
- If less than half of the text will display, show the icon only.
- If more than half of the text will display, show as much text as possible.

## Dismissal

Users can control notification visibility in the notification shade. Posting
unwanted Live Updates might cause users to revoke an app's posting permission.

To prevent users from completely disabling Live Updates, avoid posting updates
that users might dismiss. Don't repost Live Updates that the user dismissed. Use
`setDeleteIntent` to detect dismissed updates.

See the [sample app](https://github.com/android/platform-samples/tree/main/samples/user-interface/live-updates) to experiment with these APIs.