Device notifications

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.

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.

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

Was this page helpful?