This section details the different features of the library that you can make use of to implement the functionality of your turn-by-turn navigation app.
Declare navigation support in your manifest
<application> ... <service ... android:name=".MyNavigationCarAppService" android:exported="true"> <intent-filter> <action android:name="androidx.car.app.CarAppService" /> <category android:name="androidx.car.app.category.NAVIGATION"/> </intent-filter> </service> ... <application>
Support navigation intents
In order to support navigation Intents to your app, including those coming from
the Google Assistant using a voice query, your app needs to handle the
intent in its
See the documentation of
for details on the format of the intent.
Access the navigation templates
Navigation apps can access the following templates specifically designed for navigation apps. All these templates display a surface in the background that your app can access in order to draw your map, alongside other information provided by your app which varies per template.
NavigationTemplate: displays the map along with an optional informational message or routing directions and travel estimates during active navigation.
PlaceListNavigationTemplate: displays a list of places that can have corresponding markers drawn in the map.
RoutePreviewNavigationTemplate: displays a list of routes one of which can be selected and highlighted in the map.
For more details on how to design your navigation app’s user interface using those templates, see the Android for Cars App Library Design Guidelines.
In order to get access to the navigation templates, your app needs to declare
androidx.car.app.NAVIGATION_TEMPLATES permission in its
Drawing the Map
Navigation applications can access a
to draw the map on relevant templates.
In order to get access to the surface, your app needs to declare the
androidx.car.app.ACCESS_SURFACE permission in its
The map’s visible area
The host may draw user interface elements for the different templates on top of
the map. The host will communicate the area that is guaranteed to be unoccluded
and fully visible to the user by calling the
method. Also, in order to minimize the number of changes, the host will also
method with the smallest rectangle, which will always be visible based on the
For example, when a navigation app is using the
with an action strip on top, the action strip may hide itself when the user has
not interacted with the screen for a while to make more space for the map. In
this case, there will be a callback to
onVisibleAreaChanged with the same rectangle. When the action strip is hidden,
onVisibleAreaChangedwill be called with the larger area. If the user
interacts with the screen, then again only
onVisibleAreaChanged is called with
the first rectangle.
Navigation applications must redraw their map onto the
Surface instance with
the proper dark colors when the host determines that conditions warrant it, as
described in the Android Auto app quality guidelines.
In order to decide on whether you should draw a dark map you can use the
method. Whenever the dark mode status changes, you will receive a call to
Navigation applications must communicate additional navigation metadata with the host. The host makes use of the information to provide information to the vehicle head unit and to prevent navigation applications from clashing over shared resources.
val navigationManager = carContext.getCarService(NavigationManager::class.java)
NavigationManager navigationManager = carContext.getCarService(NavigationManager.class);
Starting, ending, and stopping navigation
In order for the host to manage multiple navigation apps, routing notifications,
and vehicle cluster data, it needs to be aware of the current state of
navigation. When a user starts navigation, the app should call
Similarly, when navigation ends, for example when the user arrives at their
destination or the user cancels navigation, the app should call
You should only call
when the user is finished navigating. For example, if you need to recalculate
the route in the middle of a trip, use
Occasionally, the host will need an app to stop navigation and will call
stopNavigation in a
NavigationManagerListener object provided by your app
NavigationManager.setListener. The app must then stop issuing
next-turn information in the cluster display, navigation notifications, and voice guidance.
During active navigation, the app should call
The information provided in this call will be used in the vehicle’s cluster and
heads-up displays. Not all information may be displayed to the user depending on
the particular vehicle being driven. For example, the Desktop Head Unit shows
Step added to the
Trip, but does not show
In order to test that the information is reaching the cluster the Desktop Head
Unit (DHU) tool can be configured to show a simple cluster display. Create an
cluster.ini file with the following contents:
[general] instrumentcluster = true
You can then invoke the DHU with an additional command line parameter:
dhu -c cluster.ini
The turn-by-turn (TBT) navigation instructions can be given with a frequently updated navigation notification. In order to be treated as a navigation notification in the car screen, your notification's builder must do the following:
- Mark the notification as ongoing with the
- Set the notification’s category to
- Extend the notification with a
A navigation notification will be displayed in the rail widget at the bottom of
the car screen. If the notification's importance level is set to
IMPORTANCE_HIGH, it will also be displayed as a heads-up notification (HUN).
If the importance is not set with the
method, the notification channel's importance
will be used.
is called with a value of
true, a high-importance notification will alert only
once in the HUN.
The following snippet shows how to build a navigation notification:
NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID) ... .setOnlyAlertOnce(true) .setOngoing(true) .setCategory(NotificationCompat.CATEGORY_NAVIGATION) .extend( CarAppExtender.Builder() .setContentTitle(carScreenTitle) ... .setContentIntent( PendingIntent.getBroadcast( context, ACTION_OPEN_APP.hashCode(), Intent(ACTION_OPEN_APP).setComponent( ComponentName(context, MyNotificationReceiver::class.java)), 0)) .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH) .build()) .build()
new NotificationCompat.Builder(context, NOTIFICATION_CHANNEL_ID) ... .setOnlyAlertOnce(true) .setOngoing(true) .setCategory(NotificationCompat.CATEGORY_NAVIGATION) .extend( new CarAppExtender.Builder() .setContentTitle(carScreenTitle) ... .setContentIntent( PendingIntent.getBroadcast( context, ACTION_OPEN_APP.hashCode(), new Intent(ACTION_OPEN_APP).setComponent( new ComponentName(context, MyNotificationReceiver.class)), 0)) .setImportance(NotificationManagerCompat.IMPORTANCE_HIGH) .build()) .build();
Guidelines for turn-by-turn notifications
Navigation apps should update the TBT notification regularly on distance
changes, which updates the rail widget, and only show the notification as a HUN.
Apps can control the HUN behavior by setting the notification's importance with
method. Setting the importance to
IMPORTANCE_HIGH will show a HUN, and setting
it to any other value will only update the rail widget.
To play navigation guidance over the car speakers your app must request
audio focus. As a part of your
AudioFocusRequest you should set
the usage as
AudioAttributes.USAGE_ASSISTANCE_NAVIGATION_GUIDANCE. You should
also set the focus gain as
In order to verify your app's navigation functionality when submitting it to the
Google Play Store, your app must implement the
callback. When this callback is called, your app should simulate navigation to
the chosen destination when the user begins navigation. Your app can exit this
mode whenever the current
lifecycle reaches the
You can test that your implementation of
onAutoDriveEnabled is called by
executing the following from a command line:
adb shell dumpsys activity service CAR_APP_SERVICE_NAME AUTO_DRIVE
adb shell dumpsys activity service androidx.car.app.samples.navigation.car.NavigationCarAppService AUTO_DRIVE
Default navigation car app
In Android Auto, the default navigation car app corresponds to the last navigation app that the user launched. This is the app that, for example, will receive navigation intents when the user invokes navigation commands through the assistant or when another app sends an intent to start navigation.
Allow users to interact with your map
From Car App API level 2 onwards, you can add zooming and panning to your map in
NavigationTemplate to allow users to see different parts of the map.
has three callback methods that enable you to add map interactivity to your
See the table below for how these callbacks relate to user interactions.
|Rotary nudge in Pan mode||
Map action strip
can have a map action strip for map-related actions
such as zoom in and out, recenter, display a compass, or any other actions your
app may choose to display. The map action strip can have up to four icon-only
buttons that can be refreshed without impacting task depth. Similar to the
Action Strip, the map action strip will hide during idle state and reappear on
To receive map interactivity callbacks, you must add an
Action.PAN button in the map action strip. If your app omits the
button in the map action strip, you will not receive user input from the
SurfaceCallback methods and the host will exit any previously activated
pan mode. When the user presses the pan button, the host enters
pan mode. On a touchscreen, the pan button will not be displayed.
In pan mode, the template host translates user input from non-touch input
devices, such as rotary controllers and touchpads, into the appropriate
SurfaceCallback methods. Respond to the user action to enter or exit pan mode
method in the
Builder. The host may hide other UI
components in the template while the user is in pan mode.
The stable area is updated between idle and active state. Your app should draw driving-related information such as speed, speed limit, or road warnings depending on the size of the stable area so that important information on the map doesn’t get occluded by the map action strip.