Skip to main content

Device notifications

Additional Developer Resources
A newer version of the Navigation SDK is available
This page uses v1.6.2 of the Mapbox Navigation SDK. A newer version of the SDK is available. Learn about the latest version, v2.20.2, in the Navigation SDK documentation.

The Navigation SDK contains code to customize and display Android system notifications. It automatically displays a notification when free drive mode is enabled and when a turn-by-turn navigation session begins. The notification appears in the device's notification drawer and an arrow icon is added to the status bar. Default notifications are used in a foreground service managed by the Navigation SDK's TripSession.

The Navigation SDK's free drive mode displays a default notification that includes:

Tapping on the notification returns the user back to free drive mode. The default notification will always be displayed unless otherwise overridden by a custom notification.

The NavigationNotification#updateNotification(routeProgress) method will be called every time the Navigation SDK creates a new RouteProgress update. This is your opportunity to change anything about the notification. Use a NotificationManager and your notification ID to notify the manager.

mobile Navigation UI SDK

The Navigation UI SDK's default notification displays:

  • The upcoming maneuver icon
  • Text with the location of the upcoming maneuver
  • The distance remaining until the upcoming maneuver
  • A button to end navigation

MapboxTripNotification​

Use the Navigation SDK's MapboxTripNotification class to set preferences for the default Navigation SDK notification. This notification is going to be used in a foreground service managed by the Navigation SDK's TripSession.

First, build a MapboxTripNotification:

val mapboxTripNotification = MapboxTripNotification(
    context, NavigationOptions.Builder()
        .distanceFormatter(mapboxDistanceFormatterObject)
        .timeFormatType(TimeFormatType.TWELVE_HOURS)
        .build()
)

Then give the MapboxTripNotification object to the MapboxTripService:

val mapboxTripService = MapboxTripService(applicationContext, mapboxTripNotification)

Use the notification channel​

The MapboxTripNotification class has a Kotlin Channel named notificationActionButtonChannel. The channel broadcasts MapboxTripNotification actions such as the END_NAVIGATION action, which represents when navigation has ended via a selection in the notification bar.

Access the channel with MapboxTripNotification.notificationActionButtonChannel and remove the notification with MapboxTripNotification.notificationActionButtonChannel.cancel().

Stop the MapboxTripService with NotificationAction.END_NAVIGATION:

mainJobController.scope.monitorChannelWithException(MapboxTripNotification.notificationActionButtonChannel, { notificationAction ->
    when (notificationAction) {
        NotificationAction.END_NAVIGATION ->
        mapboxTripService.stopService()
    }
})

Create a custom notification​

The Navigation SDK has a TripNotification interface so you can create your own notification if necessary. The interface defines a contract for the Android system Notification instance provider and manager.

Like the MapboxTripNotification class, your custom notification should implement the Navigation SDK's TripNotification interface.

Additional Developer Resources