Create a Live Update notification

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.

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/No Style, BigTextStyle, CallStyle, or 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 (set FLAG_ONGOING_EVENT).
• Must have a contentTitle set.
• Must NOT have any customContentView set (no RemoteViews).
• Must NOT be the summary of a group using setGroupSummary.
• The notification channel must NOT have 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.

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 or setWhen to convey important state information regarding your progress centric notification.

When time

The when time triggers a countdown for the longevity of the notification, unless the notification is dismissed or updated.

• 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 will say "5min".
• If the when time is more than 1 minute in the past the notification isn't shown.
• Use setShowWhen to FALSE if you don't want the notification shown in the shade to have a time.

Status chip appearance

The status chip always includes an icon, and optionally includes text. The chip has a maximum width of 96dp. Show the text 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.