CarAppExtender

class CarAppExtender : NotificationCompat.Extender

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:

  1. Create a NotificationCompat.Builder, setting any desired properties.
  2. Create a CarAppExtender.Builder.
  3. Set car-specific properties using the set methods of .
  4. Create a CarAppExtender by calling build.
  5. Call extend to apply the extensions to a notification.
  6. Post the notification to the notification system with the CarNotificationManager.notify(...) methods. Do not use the NotificationManager.notify(...), nor the NotificationManagerCompat.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 IMPORTANCE_HIGH, or the priority is set to 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 IMPORTANCE_DEFAULT or above, or the priority is set to PRIORITY_DEFAULT or above.
  • The notification entry will show in the notification center for all priority levels.
Calling setImportance 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 setColor.
  • 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 types

A builder of CarAppExtender.

Public constructors

Creates a CarAppExtender from the CarAppExtender of an existing notification.

Public functions
NotificationCompat.Builder

Applies car extensions to a notification that is being built.
(Mutable)List<Notification.Action!>

Returns the list of Action present on this car notification.
String?

Returns the channel id of the notification channel to use in the car.
CarColor?

Returns the background color of the notification or null if a default color is to be used.
PendingIntent?

Returns the PendingIntent to send when the notification is clicked in the car or null if not set.
CharSequence?

Returns the content text of the notification or null if not set.
CharSequence?

Returns the content title for the notification or null if not set.
PendingIntent?

Returns the PendingIntent to send when the notification is cleared by the user or null if not set.
Int

Returns the importance of the notification in the car screen.
Bitmap?

Returns the large icon bitmap to display in the notification or null if not set.
@DrawableRes Int

Returns the resource ID of the small icon drawable to use.
java-static Boolean
isExtended(notification: Notification)

Returns whether the given notification was extended with CarAppExtender.

Public constructors

CarAppExtender

Added in 1.0.0
CarAppExtender(notification: Notification)

Creates a CarAppExtender from the CarAppExtender of an existing notification.

Public functions

extend

Added in 1.0.0
fun extend(builder: NotificationCompat.Builder): NotificationCompat.Builder

Applies car extensions to a notification that is being built.

This is typically called by extend.

Throws
java.lang.NullPointerException

if builder is null

getActions

Added in 1.0.0
fun getActions(): (Mutable)List<Notification.Action!>

Returns the list of Action present on this car notification.

See also
addAction

getChannelId

Added in 1.1.0
fun getChannelId(): String?

Returns the channel id of the notification channel to use in the car.

See also
setChannelId

getColor

Added in 1.0.0
fun getColor(): CarColor?

Returns the background color of the notification or null if a default color is to be used.

See also
setColor

getContentIntent

Added in 1.0.0
fun getContentIntent(): PendingIntent?

Returns the PendingIntent to send when the notification is clicked in the car or null if not set.

See also
setContentIntent

getContentText

Added in 1.0.0
fun getContentText(): CharSequence?

Returns the content text of the notification or null if not set.

See also
setContentText

getContentTitle

Added in 1.0.0
fun getContentTitle(): CharSequence?

Returns the content title for the notification or null if not set.

See also
setContentTitle

getDeleteIntent

Added in 1.0.0
fun getDeleteIntent(): PendingIntent?

Returns the PendingIntent to send when the notification is cleared by the user or null if not set.

See also
setDeleteIntent

getImportance

Added in 1.0.0
fun getImportance(): Int

Returns the importance of the notification in the car screen.

See also
setImportance

getLargeIcon

Added in 1.0.0
fun getLargeIcon(): Bitmap?

Returns the large icon bitmap to display in the notification or null if not set.

See also
setLargeIcon

getSmallIcon

Added in 1.0.0
fun getSmallIcon(): @DrawableRes Int

Returns the resource ID of the small icon drawable to use.

See also
setSmallIcon

isExtended

Added in 1.0.0
java-static fun isExtended(notification: Notification): Boolean

Returns whether the given notification was extended with CarAppExtender.

Throws
java.lang.NullPointerException

if notification is null