General Customizations

Customizing FerrostarCore behaviors

FerrostarCore sits at the heart of your interactions with Ferrostar. It provides an idiomatic way to interact with the core from native code at the platform layer.

Ferrostar NavigationControllerConfig options

These customizations apply to the NavigationController. They are surfaced at the platform layer as an argument to the startNavigation method of FerrostarCore.

Waypoint advance

The waypoint advance is configured by the WaypointAdvanceMode. Our original (V0.27.0 and earlier) hardcoded implementation simply checked if the user was within 100 meters of the waypoint when the step was being advanced. The waypoint advance logic is separated from step advance to ensure that the user will advance waypoint regardless of step advance conditions.

To match Ferrostar's original default, use WaypointAdvanceMode::WaypointWithinRange(100.0).

The waypoint advance mode has access to the entire TripState anytime the user location is updated. As a result more complex implementations would be welcome additions to the library.

Step advance

The step advance system uses a common StepAdvanceCondition trait that tells the NavigationController whether to advance the step or not on every iteration (user location update). Several implementations are provided:

If you want a new condition, the trait is relatively simple to implement and PR's are welcome! (Note that currently these must be written in Rust directly.)

The customizable step advance conditions are designed to help you create more complex and flexible step advancement logic. You can also combine multiple conditions using the OrAdvanceConditions and AndAdvanceConditions.

Recommended conditions

The DistanceEntryAndExitCondition is ideal for most navigation use cases, but may be overkill in certain cases. Its primary focus is on ensuring the user has approximately reached the end of the step, and then intentionally proceeded past it. This is particularly useful for scenarios like stop lights, where the simpler DistanceToEndOfStepCondition would appear to make the maneuver before the user has actually done so in real life.

The OrAdvanceConditions may be useful to attach a backup condition to ensure the user doesn't get stuck when offline. E.g. the user may have lost connection and missed a step's end only to then re-joined the route. In a situation like this you could add an Or with DistanceFromStepCondition with a very large value to effectively clean up a stuck state while offline.

Route deviation tracking

Ferrostar recognizes that there is no one-size-fits-all solution for determining when a user has deviated from the intended route. The core provides several configurable detection strategies, but you can also bring your own. (And yes, you can write your custom deviation detection code in your native mobile codebase.)

See the RouteDeviationTracking rustdocs for the list of available strategies and parameters. (The Rust API is bridged idiomatically to Swift and Kotlin.)

Configuring a RouteDeviationHandler

By default, Ferrostar will fetch new routes when the user goes off course. You can override this behavior with hooks on FerrostarCore.

On iOS, all customization happens via the delegate. Implement the core:correctiveActionForDeviation:remainingWaypoints method on your delegate and you’re all set. On Android, set the deviationHandler property.

Refer to the demo apps for custom implementation examples. Note that you can disable the default behavior of attempting to reroute by setting an empty implementation (not setting the property to nil/null!).

Alternate route handling

FerrostarCore may occasionally load alternative routes. At this point, this is only used for recalculating when the user deviates from the route, but it may be used for additional behaviors in the future, such as speculative route checking based on current traffic (for supported vendors).

By default, Ferrostar will “accept” the new route and reroute the active navigation session whenever a new route arrives while the user is off course.

On iOS, you can configure this behavior by adding a delegate to the core and implementing the core:loadedAlternateRoutes method. On Android, you can configure this behavior by providing an AlternateRouteProcessor implementation to FerrostarCore.

Refer to the demo apps examples of custom implementations.

Note that you can disable the default behavior of attempting to reroute by setting an empty implementation (not setting the property to nil/ null!).

Customizing prompt timings

While most APIs don’t offer customizable timing for banners and spoken prompts, you can edit the standardized Route responses directly! A functional map operation drilling down to the instructions is an elegant way to change trigger distances.