CarPlayManagerDelegate

@available(iOS 12.0, *)
public protocol CarPlayManagerDelegate : AnyObject, UnimplementedLogging, CarPlayManagerDelegateDeprecations

CarPlayManagerDelegate is the main integration point for Mapbox CarPlay support.

Implement this protocol and assign an instance to the delegate property of the shared instance of CarPlayManager.

If no delegate is set, a default built-in MapboxNavigationService will be created and used when a trip begins.

  • Offers the delegate an opportunity to provide a customized list of leading bar buttons at the root of the template stack for the given activity.

    These buttons’ tap handlers encapsulate the action to be taken, so it is up to the developer to ensure the hierarchy of templates is adequately navigable.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        leadingNavigationBarButtonsCompatibleWith traitCollection: UITraitCollection,
                        in carPlayTemplate: CPTemplate,
                        for activity: CarPlayActivity) -> [CPBarButton]?

    Parameters

    carPlayManager

    The CarPlay manager instance.

    traitCollection

    The trait collection of the view controller being shown in the CarPlay window.

    carPlayTemplate

    The template into which the returned bar buttons will be inserted.

    activity

    What the user is currently doing on the CarPlay screen. Use this parameter to distinguish between multiple templates of the same kind, such as multiple CPMapTemplates.

    Return Value

    An array of bar buttons to display on the leading side of the navigation bar while template is visible.

  • Offers the delegate an opportunity to provide a customized list of trailing bar buttons at the root of the template stack for the given activity.

    These buttons’ tap handlers encapsulate the action to be taken, so it is up to the developer to ensure the hierarchy of templates is adequately navigable.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        trailingNavigationBarButtonsCompatibleWith traitCollection: UITraitCollection,
                        in carPlayTemplate: CPTemplate,
                        for activity: CarPlayActivity) -> [CPBarButton]?

    Parameters

    carPlayManager

    The CarPlay manager instance.

    traitCollection

    The trait collection of the view controller being shown in the CarPlay window.

    carPlayTemplate

    The template into which the returned bar buttons will be inserted.

    activity

    What the user is currently doing on the CarPlay screen. Use this parameter to distinguish between multiple templates of the same kind, such as multiple CPMapTemplates.

    Return Value

    An array of bar buttons to display on the trailing side of the navigation bar while template is visible.

  • Offers the delegate an opportunity to provide a customized list of buttons displayed on the map.

    These buttons handle the gestures on the map view, so it is up to the developer to ensure the map template is interactive. If this method is not implemented, or if nil is returned, a default set of zoom and pan buttons declared in the CarPlayMapViewController will be provided.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        mapButtonsCompatibleWith traitCollection: UITraitCollection,
                        in carPlayTemplate: CPTemplate,
                        for activity: CarPlayActivity) -> [CPMapButton]?

    Parameters

    carPlayManager

    The CarPlay manager instance.

    traitCollection

    The trait collection of the view controller being shown in the CarPlay window.

    carPlayTemplate

    The template into which the returned map buttons will be inserted.

    activity

    What the user is currently doing on the CarPlay screen. Use this parameter to distinguish between multiple templates of the same kind, such as multiple CPMapTemplates.

    Return Value

    An array of map buttons to display on the map while template is visible.

  • carPlayManager(_:willPreview:) Default implementation

    Offers the delegate the opportunity to customize a trip before it is presented to the user to preview.

    To customize the destination’s title, which is displayed when a route is selected, set the MKMapItem.name property of the CPTrip.destination property. To add a subtitle, create a new MKMapItem whose MKPlacemark has the Street key in its address dictionary.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        willPreview trip: CPTrip) -> CPTrip

    Parameters

    carPlayManager

    The CarPlay manager instance.

    trip

    The trip that will be previewed.

    Return Value

    The actual trip to be previewed. This can be the same trip or a new/alternate trip if desired.

  • carPlayManager(_:willPreview:with:) Default implementation

    Offers the delegate the opportunity to customize a trip preview text configuration for a given trip.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        willPreview trip: CPTrip,
                        with previewTextConfiguration: CPTripPreviewTextConfiguration) -> CPTripPreviewTextConfiguration

    Parameters

    carPlayManager

    The CarPlay manager instance.

    trip

    The trip that will be previewed.

    previewTextConfiguration

    The trip preview text configuration that will be presented alongside the trip.

    Return Value

    The actual preview text configuration to be presented alongside the trip.

  • Offers the delegate the opportunity to react to selection of a trip. Certain trips may have alternate route(s).

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        selectedPreviewFor trip: CPTrip,
                        using routeChoice: CPRouteChoice)

    Parameters

    carPlayManager

    The CarPlay manager instance.

    trip

    The trip to begin navigating along.

    routeChoice

    The possible route for the chosen trip.

  • Asks the delegate to provide a navigation service. In multi-screen applications this should be the same instance used to guide the user along the route on the phone.

    Important

    this method is superseeded by carPlayManager(_:navigationServiceFor:desiredSimulationMode:), and it’s call result will be preferred over current method’s.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    @available(*, deprecated, renamed: "carPlayManager(_:navigationServiceFor:desiredSimulationMode:﹚")
    func carPlayManager(_ carPlayManager: CarPlayManager,
                        navigationServiceFor routeResponse: RouteResponse,
                        routeIndex: Int,
                        routeOptions: RouteOptions,
                        desiredSimulationMode: SimulationMode) -> NavigationService?

    Parameters

    carPlayManager

    The CarPlay manager instance.

    routeResponse

    The RouteResponse containing a route for which the returned route controller will manage location updates.

    routeIndex

    The index of the route within the original RouteResponse object.

    routeOptions

    the options that were specified for the route request.

    desiredSimulationMode

    The desired simulation mode to use.

    Return Value

    A navigation service that manages location updates along route.

  • Asks the delegate to provide a navigation service. In multi-screen applications this should be the same instance used to guide the user along the route on the phone.

    Important

    Implementing this method will suppress carPlayManager(_:navigationServiceFor:routeIndex:routeOptions:desiredSimulationMode:) being called, using current one as the source of truth for providing navigation service.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        navigationServiceFor indexedRouteResponse: IndexedRouteResponse,
                        desiredSimulationMode: SimulationMode) -> NavigationService?

    Parameters

    carPlayManager

    The CarPlay manager instance.

    indexedRouteResponse

    The IndexedRouteResponse containing a route, index and options for which the returned route controller will manage location updates.

    desiredSimulationMode

    The desired simulation mode to use.

    Return Value

    A navigation service that manages location updates along route.

  • Called when the CarPlay manager fails to fetch a route.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        didFailToFetchRouteBetween waypoints: [Waypoint]?,
                        options: RouteOptions,
                        error: DirectionsError) -> CPNavigationAlert?

    Parameters

    carPlayManager

    The CarPlay manager instance.

    waypoints

    the waypoints for which a route could not be retrieved.

    options

    The route options that were attached to the route request.

    error

    The error returned from the directions API.

    Return Value

    Optionally, a CPNavigationAlert to present to the user. If this method returns an alert, the CarPlay manager will transition back to the map template and display the alert. If it returns nil, the CarPlay manager will do nothing.

  • Called when navigation begins so that the containing app can update accordingly.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        didBeginNavigationWith service: NavigationService)

    Parameters

    carPlayManager

    The CarPlay manager instance.

    service

    The navigation service that has begun managing location updates for a navigation session.

  • Called when navigation is about to be finished so that the containing app can update accordingly. This delegate method will be called before dismissing CarPlayNavigationViewController.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManagerWillEndNavigation(_ carPlayManager: CarPlayManager, byCanceling canceled: Bool)

    Parameters

    carPlayManager

    The CarPlay manager instance.

    canceled

    A Boolean value indicating whether this method is being called because the user intends to cancel the trip, as opposed to letting it run to completion.

  • carPlayManagerDidEndNavigation(_:) Default implementation

    Called when navigation ends so that the containing app can update accordingly. This delegate method will be called after dismissing CarPlayNavigationViewController.

    If you need to know whether the navigation ended because the user arrived or canceled it, use the carPlayManagerDidEndNavigation(_:byCanceling:) method.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManagerDidEndNavigation(_ carPlayManager: CarPlayManager)

    Parameters

    carPlayManager

    The CarPlay manager instance.

  • Called when navigation ends so that the containing app can update accordingly. This delegate method will be called after dismissing CarPlayNavigationViewController.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManagerDidEndNavigation(_ carPlayManager: CarPlayManager, byCanceling canceled: Bool)

    Parameters

    carPlayManager

    The CarPlay manager instance.

    canceled

    A Boolean value indicating whether this method is being called because the user canceled the trip, as opposed to letting it run to completion/being canceled by the system.

  • Called when the CarPlayManager detects the user arrives at the destination waypoint for a route leg.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        shouldPresentArrivalUIFor waypoint: Waypoint) -> Bool

    Parameters

    carPlayManager

    The CarPlay manager instance that has arrived at a waypoint.

    waypoint

    The waypoint that the user has arrived at.

    Return Value

    A boolean value indicating whether to show an arrival UI.

  • Called when the carplay manager will disable the idle timer.

    Implementing this method will allow developers to change whether idle timer is disabled when CarPlay is connected and the vice-versa when disconnected.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManagerShouldDisableIdleTimer(_ carPlayManager: CarPlayManager) -> Bool

    Parameters

    carPlayManager

    The CarPlay manager instance.

    Return Value

    A Boolean value indicating whether to disable idle timer when carplay is connected and enable when disconnected.

  • carPlayManager(_:didPresent:) Default implementation

    Called when the CarPlayManager presents a new CarPlayNavigationViewController upon start of a navigation session.

    Implementing this method will allow developers to query or customize properties of the presented CarPlayNavigationViewController. For example, a developer may wish to perform custom map styling on the presented NavigationMapView.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        didPresent navigationViewController: CarPlayNavigationViewController)

    Parameters

    carPlayManager

    The CarPlay manager instance.

    navigationViewController

    The CarPlayNavigationViewController that was presented on the CarPlay display.

  • Tells the receiver that the PointAnnotation representing the final destination was added to either CarPlayMapViewController or CarPlayNavigationViewController.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        didAdd finalDestinationAnnotation: PointAnnotation,
                        to parentViewController: UIViewController,
                        pointAnnotationManager: PointAnnotationManager)

    Parameters

    carPlayManager

    The CarPlayManager object.

    finalDestinationAnnotation

    The point annotation that was added to the map view.

    parentViewController

    The view controller that contains the map view, which is an instance of either CarPlayMapViewController or CarPlayNavigationViewController.

    pointAnnotationManager

    The object that manages the point annotation in the map view.

  • Determines if the maneuver should be presented as a notification when the app is in the background.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        shouldShowNotificationFor maneuver: CPManeuver,
                        in mapTemplate: CPMapTemplate) -> Bool

    Parameters

    carPlayManager

    The CarPlayManager object.

    maneuver

    Maneuver, for which notification will be shown.

    mapTemplate

    The map template that is visible during either preview or navigation sessions.

    Return Value

    A boolean value indicating whether maneuver should appear as a notification.

  • Determines if the updated distance remaining for the maneuver should be presented as a notification when the app is in the background.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        shouldShowNotificationFor navigationAlert: CPNavigationAlert,
                        in mapTemplate: CPMapTemplate) -> Bool

    Parameters

    carPlayManager

    The CarPlayManager object.

    navigationAlert

    Banner alert, for which notification will be shown.

    mapTemplate

    The map template that is visible during either preview or navigation sessions.

    Return Value

    A boolean value indicating whether alert should appear as a notification.

  • Determines if the navigation alert should be presented as a notification when the app is in the background.

    Default Implementation

    UnimplementedLogging prints a warning to standard output the first time this method is called.

    Declaration

    Swift

    func carPlayManager(_ carPlayManager: CarPlayManager,
                        shouldUpdateNotificationFor maneuver: CPManeuver,
                        with travelEstimates: CPTravelEstimates,
                        in mapTemplate: CPMapTemplate) -> Bool

    Parameters

    carPlayManager

    The CarPlayManager object.

    maneuver

    Maneuver, for which notification will be shown.

    travelEstimates

    Object that describes the time and distance remaining for the active navigation session.

    mapTemplate

    The map template that is visible during either preview or navigation sessions.

    Return Value

    A boolean value indicating whether updated estimates should appear in the notification.