CarAppExtender
public
final
class
CarAppExtender
extends Object
implements
NotificationCompat.Extender
java.lang.Object | |
↳ | androidx.car.app.notification.CarAppExtender |
Helper class to add car app extensions to notifications.
By default, notifications in a car screen have the properties provided by
NotificationCompat.Builder
. This helper class provides methods to
override those properties for the car screen. However, notifications only show up in the car
screen if it is extended with CarAppExtender
, even if the extender does not override any
properties. To create a notification with car extensions:
- Create a
NotificationCompat.Builder
, setting any desired properties. - Create a
CarAppExtender.Builder
. - Set car-specific properties using the
set
methods ofCarAppExtender.Builder
. - Create a
CarAppExtender
by callingCarAppExtender.Builder.build()
. - Call
NotificationCompat.Builder.extend(NotificationCompat.Extender)
to apply the extensions to a notification. - Post the notification to the notification system with the
NotificationManagerCompat.notify(...)
methods and not theNotificationManager.notify(...)
methods.
Notification notification = new NotificationCompat.Builder(context) ... .extend(new CarAppExtender.Builder() .set*(...) .build()) .build();
Car extensions can be accessed on an existing notification by using the CarAppExtender(Notification)
constructor, and then using the get
methods to access
values.
The car screen UI is affected by the notification channel importance (Android O and above) or notification priority (below Android O) in the following ways:
- A heads-up-notification (HUN) will show if the importance is set to
NotificationManagerCompat.IMPORTANCE_HIGH
, or the priority is set toNotificationCompat.PRIORITY_HIGH
or above. - The notification center icon, which opens a screen with all posted notifications when
tapped, will show a badge for a new notification if the importance is set to
NotificationManagerCompat.IMPORTANCE_DEFAULT
or above, or the priority is set toNotificationCompat.PRIORITY_DEFAULT
or above. - The notification entry will show in the notification center for all priority levels.
CarAppExtender.Builder.setImportance(int)
will override the importance for the notification in
the car screen.
Calling NotificationCompat.Builder#setOnlyAlertOnce(true)
will alert a high-priority
notification only once in the HUN. Updating the same notification will not trigger another HUN
event.
Navigation
For a navigation app's turn-by-turn (TBT) notifications, which update the same notification
frequently with navigation information, the notification UI has a slightly different behavior.
The app can post a TBT notification by calling NotificationCompat.Builder#setOngoing(true)
and NotificationCompat.Builder#setCategory(NotificationCompat.CATEGORY_NAVIGATION)
.
TBT notifications behave the same as regular notifications with the following exceptions:
- The notification will not be displayed if the navigation app is not the currently active navigation app, or if the app is already displaying routing information in the navigation template.
- The heads-up-notification (HUN) can be customized with a background color through
CarAppExtender.Builder.setColor(CarColor)
. - The notification will not be displayed in the notification center.
In addition to that, the information in the navigation notification will be displayed in the rail widget at the bottom of the screen when the app is in the background.
Note that frequent HUNs distract the driver. The recommended practice is to update the TBT
notification regularly on distance changes, which updates the rail widget, but call NotificationCompat.Builder#setOnlyAlertOnce(true)
unless there is a significant navigation turn
event.
Summary
Nested classes | |
---|---|
class |
CarAppExtender.Builder
A builder of |
Public constructors | |
---|---|
CarAppExtender(Notification notification)
Creates a |
Public methods | |
---|---|
NotificationCompat.Builder
|
extend(NotificationCompat.Builder builder)
Applies car extensions to a notification that is being built. |
List<Notification.Action>
|
getActions()
Returns the list of |
CarColor
|
getColor()
Returns the background color of the notification or |
PendingIntent
|
getContentIntent()
Returns the |
CharSequence
|
getContentText()
Returns the content text of the notification or |
CharSequence
|
getContentTitle()
Returns the content title for the notification or |
PendingIntent
|
getDeleteIntent()
Returns the |
int
|
getImportance()
Returns the importance of the notification in the car screen. |
Bitmap
|
getLargeIcon()
Returns the large icon bitmap to display in the notification or |
int
|
getSmallIcon()
Returns the resource ID of the small icon drawable to use. |
static
boolean
|
isExtended(Notification notification)
Returns whether the given notification was extended with |
Inherited methods | |
---|---|
Public constructors
CarAppExtender
public CarAppExtender (Notification notification)
Creates a CarAppExtender
from the CarAppExtender
of an existing notification.
Parameters | |
---|---|
notification |
Notification |
Public methods
extend
public NotificationCompat.Builder extend (NotificationCompat.Builder builder)
Applies car extensions to a notification that is being built.
This is typically called by
NotificationCompat.Builder.extend(NotificationCompat.Extender)
.
Parameters | |
---|---|
builder |
NotificationCompat.Builder : the builder to be modified. |
Returns | |
---|---|
NotificationCompat.Builder |
the build object for chaining. |
Throws | |
---|---|
NullPointerException |
if builder is null
|
getActions
public List<Notification.Action> getActions ()
Returns the list of Notification.Action
present on this car notification.
Returns | |
---|---|
List<Notification.Action> |
getColor
public CarColor getColor ()
Returns the background color of the notification or null
if a default color is to
be used.
Returns | |
---|---|
CarColor |
getContentIntent
public PendingIntent getContentIntent ()
Returns the PendingIntent
to send when the notification is clicked in the car or
null
if not set.
Returns | |
---|---|
PendingIntent |
getContentText
public CharSequence getContentText ()
Returns the content text of the notification or null
if not set.
Returns | |
---|---|
CharSequence |
getContentTitle
public CharSequence getContentTitle ()
Returns the content title for the notification or null
if not set.
Returns | |
---|---|
CharSequence |
getDeleteIntent
public PendingIntent getDeleteIntent ()
Returns the PendingIntent
to send when the notification is cleared by the user or
null
if not set.
Returns | |
---|---|
PendingIntent |
getImportance
public int getImportance ()
Returns the importance of the notification in the car screen.
Returns | |
---|---|
int |
getLargeIcon
public Bitmap getLargeIcon ()
Returns the large icon bitmap to display in the notification or null
if not set.
Returns | |
---|---|
Bitmap |
getSmallIcon
public int getSmallIcon ()
Returns the resource ID of the small icon drawable to use.
Returns | |
---|---|
int |
See also:
isExtended
public static boolean isExtended (Notification notification)
Returns whether the given notification was extended with CarAppExtender
.
Parameters | |
---|---|
notification |
Notification |
Returns | |
---|---|
boolean |
Throws | |
---|---|
NullPointerException |
if notification is null
|
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2021-02-24 UTC.