Getting Started on iOS

This section of the guide covers how to integrate Ferrostar into an iOS app. We'll cover the "batteries included" approach, but flag areas for customization and overrides along the way.

Add the Swift package dependency

If you’re not familiar with adding Swift Package dependencies to apps, Apple has some helpful documentation. You can search for the repository via its URL: https://github.com/stadiamaps/ferrostar.

Configure location services

In order to access the user’s location, you’ll need to set a key in your Info.plist or similar file. This is something you can set in Xcode by going to your project, selecting the target, and going to the Info tab.

You need to add row for “Privacy - Location When In Use Usage Description” (right-click any of the existing rows and click “Add row”) or, if you’re using raw keys, NSLocationWhenInUseUsageDescription. Fill in a description of why your app needs access to their location. Presumably something related to navigation ;)

Location providers

You'll need to configure a provider to get location updates. We bundle a few implementations to get you started, or you can create your own. The broad steps are the same regardless of which provider you use: create an instance of the class, store it in an instance variable where it makes sense, and (if simulating a route) set the location manually or enter a simulated route.

The API is similar to the iOS location APIs you may already know, and you can start or stop updates at will.

You should store your location provider in a place that is persistent for as long as you need it. Most often this makes sense as a private @StateObject if you’re using SwiftUI.

`CoreLocationProvider`

The CoreLocationProvider provides a ready-to-go wrapper around a CLLocationManager for getting location updates from GNSS. It will automatically request permissions for you as part of initialization.

@StateObject private var locationProvider = CoreLocationProvider(activityType: .otherNavigation)

`SimulatedLocationProvider`

The SimulatedLocationProvider allows for simulating location within Ferrostar without needing GPX files or complicated environment setup. This is great for testing and development without stepping outside.

First, instantiate the class. This is usually saved as an instance variable.

@StateObject private var locationProvider = SimulatedLocationProvider(location: initialLocation)

You can set a new location using the lastLocation property at any time. Optionally, once you have a route, simulate the replay of the route. You can set a warpFactor to play it back faster.

locationProvider.warpFactor = 2
locationProvider.setSimulatedRoute(route)

Configure the `FerrostarCore` instance

Next, you’ll want to create a FerrostarCore instance. This is your interface into Ferrostar. You’ll also want to keep this around as a persistent property and use it in SwiftUI using a private @StateObject or @ObservedObject in most situations.

FerrostarCore provides several initializers, including convenient initializers for Valhalla routing backends and the ability to provide your own custom routing (ex: for local/offline use).

Route Providers

You’ll need to decide on a route provider when you set up your FerrostarCore instance. For limited testing, FOSSGIS maintains a public server with the URL https://valhalla1.openstreetmap.de/route. For production use, you’ll need another solution like a commercial vendor or self-hosting.

Getting a route

Before getting routes, you’ll need the user’s current location. You can get this from the location provider (which is part of why you’ll want to hang on to it). Next, you’ll need a set of waypoints to visit. Finally, you can use the asynchronous getRoutes method on FerrostarCore. Here’s an example:

Task {
    do {
        routes = try await ferrostarCore.getRoutes(initialLocation: userLocation, waypoints: [Waypoint(coordinate: GeographicCoordinate(cl: loc.location), kind: .break)])

        errorMessage = nil
        
        // TODO: Let the user select a route, or pick one programmatically
    } catch {
        // Communicate the error to the user.
        errorMessage = "Error: \(error)"
    }
}

Once you or the user has selected a route, it’s time to start navigating!

try ferrostarCore.startNavigation(route: route, config: SwiftNavigationControllerConfig(stepAdvance: .relativeLineStringDistance(minimumHorizontalAccuracy: 32, automaticAdvanceDistance: 10), routeDeviationTracking: .staticThreshold(minimumHorizontalAccuracy: 25, maxAcceptableDeviation: 25)))

From this point, FerrostarCore automatically starts the LocationProvider updates, and will use Combine, the SwiftUI observation framework, to publish state changes.

Using the NavigationMapView

So now navigation is “started” but what does that mean? Let’s turn these state updates into a familiar map-centric experience!

We’ll use the DynamicallyOrientingNavigationView together with a map style, the state from the core, and many more configurable properties See the class documentation for details on each parameter, but you have the ability to customize most of the camera behavior.

// NOTE: You can get a free Stadia Maps API key at https://client.stadiamaps.com
let styleURL = URL(string: "https://tiles.stadiamaps.com/styles/outdoors.json?api_key=\(stadiaMapsAPIKey)")!
DynamicallyOrientingNavigationView(
    styleURL: styleURL,
    navigationState: state,
    camera: $camera,
    snappedZoom: .constant(18),
    useSnappedCamera: .constant(true))

Demo app

We've put together a minimal demo app with an example integration.

Going deeper

This covers the basic “batteries included” configuration which works for simple apps. But there’s a lot of room for customization! Skip on over to the customization chapters that interest you.

The Ferrostar User Guide