Google is committed to advancing racial equity for Black communities. See how.

CarAppExtender

public class CarAppExtender
extends Object implements NotificationCompat.Extender

java.lang.Object
   ↳ com.google.android.libraries.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:

  1. Create a NotificationCompat.Builder, setting any desired properties.
  2. Create a CarAppExtender.Builder with builder().
  3. Set car-specific properties using the set methods of CarAppExtender.Builder.
  4. Create a CarAppExtender by calling CarAppExtender.Builder.build().
  5. Call NotificationCompat.Builder.extend(NotificationCompat.Extender) to apply the extensions to a notification.
  6. Post the notification to the notification system with the NotificationManagerCompat.notify(...) methods and not the NotificationManager.notify(...) methods.
 Notification notification = new NotificationCompat.Builder(context)
         ...
         .extend(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:

Calling 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.

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). The car screen UI is affected in the following ways:

  • The same heads-up-notification (HUN) behavior as regular notifications.
  • A rail widget at the bottom of the screen will show when the navigation 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 CarAppExtender

Public methods

static CarAppExtender.Builder builder()

Creates a CarAppExtender.Builder.

NotificationCompat.Builder extend(NotificationCompat.Builder builder)

Applies car extensions to a notification that is being built.

Inherited methods

Public methods

builder

public static CarAppExtender.Builder builder ()

Creates a CarAppExtender.Builder.

Returns
CarAppExtender.Builder

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(android.support.v4.app.NotificationCompat.Extender).

Parameters
builder NotificationCompat.Builder

Returns
NotificationCompat.Builder

Throws
NullPointerException if builder is null.