Beta
Maps SDK for iOS v10

User location

The Mapbox Maps SDK for iOS enables your application to observe and respond to the user's location. It helps you request permission to access a user's location, use a location provider to get location information for the device, and display the user's location on the map visually.

Privacy and permissions

Users must grant your application permission before it can access information about their location. During this permission prompt, a custom string may be presented explaining how location will be used. This is specified by adding the key NSLocationWhenInUseUsageDescription to the Info.plist file with a value that describes why the application is requesting these permissions.

Prior to iOS 14, the device could only send the user’s exact location. With iOS 14, users can opt into Approximate Location. Since users may toggle precise location off when initial permission for their location is requested by the app or in the System settings, developers are strongly encouraged to support Approximate Location.

Request temporary access to precise location

Certain application features may require precise location. The Mapbox Maps SDK for iOS provides a wrapper of Apple’s CoreLocation APIs that requests temporary access to precise location when the user has opted out at the application settings level:

mapView.location.requestTemporaryFullAccuracyPermissions(withPurposeKey: "customKey")

Make the following adjustments to your Info.plist file to provide explanations for system prompts that may appear during location prompts:

  • Provide users with a brief explanation of how the app will use their location data for temporary access:
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>Your precise location is used to calculate turn-by-turn directions, show your location on the map, and help improve the map.</string>
    
  • Add LocationAccuracyAuthorizationDescription as an element of the NSLocationTemporaryUsageDescriptionDictionary dictionary to give users a brief explanation of why a feature in your app requires their exact location:
    <key>NSLocationTemporaryUsageDescriptionDictionary</key>
    <dict>
      <key>LocationAccuracyAuthorizationDescription</key>
      <string>Please enable precise location. Turn-by-turn directions only work when precise location data is available.</string>
    </dict>
    

Handle changes in location authorization

At any point, a user may grant or revoke access to precise location in System settings. The Maps SDK for iOS's LocationPermissionsDelegate protocol has a set of delegate methods that will be called when the user makes changes to location permissions.

After the current session elapses, your users will be prompted to give location permissions the next time they open your app. Your users must enable precise location during this prompt or in the app’s System settings to avoid being asked repeatedly for location accuracy permissions.

Customize accuracy authorization handling

If you want to customize how accuracy authorization updates are handled, use the location permission delegate. The LocationPermissionsDelegate protocol has a set of delegate methods that will be called when the user makes changes to location permissions.

class ViewController: UIViewController {
    // This controller's initialization has been omitted in this code snippet
    var mapView: MapView! 

    override func viewDidLoad() {
        super.viewDidLoad()
        mapView.locationManager.delegate = self
    }

    // Selector that will be called as a result of the delegate below
    func requestPermissionsButtonTapped() {
        mapView.locationManager.requestTemporaryFullAccuracyPermissions(withPurposeKey: "customKey")
    }
}

extension ViewController: LocationPermissionsDelegate {
    func locationManager(_ locationManager: LocationManager, didChangeAccuracyAuthorization accuracyAuthorization: CLAccuracyAuthorization) {
        if accuracyAuthorization == .reducedAccuracy {
         // Perform an action in response to the new change in accuracy
        }
    }
}

The code above uses on a withPurposeKey parameter to handle a location permission change. This value must correspond to the key of a key/value pair that was specified in Info.plist.

<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>CustomKey<key>
    <string>We temporarily require your precise location for an optimal experience.</string>
</dict>

Location provider

A location provider is a protocol encapsulating functions and properties that will handle location updates, permission changes, and more. It has a delegate pattern so it will notify the delegate when changes in location occur.

By default, the Maps SDK will use its own default location provider, but you can also choose to use a custom location provider.

Custom location providers

When using a custom location provider, it must conform to the LocationProvider protocol and implement the required functions from the protocol. The custom provider can be passed to the LocationManager with the following code:

mapView.locationManager.overrideLocationProvider(with: customLocationProvider)

Location puck

Enabling user location in MapOptions will render a puck on the map that shows the device's current location and handle requesting permissions and all the nuances that come with different permission levels.

Enable the default user location display using the following code:

mapView.location.options.puckType = .puck2D()
example
Show the user's location on the map

Show the user's location on a map using the default location puck.

Set puck style options

There are several options to customize the appearance of the location puck using LocationOptions. Using the PuckType enum, you can set whether to use a 2D or 3D puck.

Set Puck Bearing Source

On iOS, the user location can track bearing using the device heading or device course. This option can be set in LocationOptions.