Runtime Location. Part 1: The Blue Dot
The Blue Dot
Often your app needs to show your location, or a "blue dot", on a map. Maybe it's important to know where you are, or important to know where things are in relation to you. Often that context is critical to the core functionality of the app.
Runtime provides a robust blue dot experience. Out of the box, you simply call start() or stop() and Runtime takes care of talking to your device to get the best available location.
But Runtime takes this functionality further and provides a flexible framework to provide your own location source. Perhaps you need to connect to an external GPS unit or use a proprietary indoor location beacon system.
In this, the first of 3 posts on the topic, we'll take a look at how Runtime presents location in the map view. In part 2 we'll discuss how Runtime gets location updates from various location data sources and cover what it takes to create your own location data source. Finally, in part 3, we'll take what we've learnt so far and build a custom location data source.
Your location in the Runtime
There are 3 Runtime components that work together to put that blue dot on your map: AGSMapView, AGSLocationDisplay, and AGSLocationDataSource
- Every AGSMapView has an AGSLocationDisplay. It is responsible for showing and updating the current location on that map view.
- You access the AGSLocationDisplay via the AGSMapView.locationDisplay property.
- Your app starts and stops tracking location by calling AGSLocationDisplay.start(completion) and AGSLocationDisplay.stop().
Swift Note:
Swift translates method names automatically from Objective-C, so while the API doc references, for example, startWithCompletion:(), in Swift it will be written start(completion) and that's the form I'll use in this post.
Various properties on AGSLocationDisplay determine what the location display looks like on the map view (you don't have to use a blue dot if your app needs something else) and how the map view keeps up with the current location.
If you just want to use your device's built-in GPS, that's actually all you need to know. But let's look at some ways to control and configure that location display…
AGSLocationDisplay
There are 3 key aspects of Location Display that you can change.
- Behavior: How does the map view update itself as the current location changes.
- Appearance: What does the location display look like and how does it change depending on what information is available?
- Data Source: Where does the location display get the current location from?
Configuring behaviour
The auto-pan mode changes how the AGSMapView keeps up with location updates, that is, how does the map view move to follow the blue dot around. Set the auto-pan mode using AGSLocationDisplay.autoPanMode.
| Mode | Purpose and behavior |
|---|---|
| Off | This is the default. The blue dot is free to move around your map display (or beyond it) while the map view remains still. |
| Recenter |
The map will follow the blue dot as it moves, based off the AGSLocationDisplay.wanderExtentFactor, a number between 0 and 1:
|
|
Navigation |
Good for driving. The map view updates for the current location, but orients to the direction of motion. Use the AGSLocationDisplay.navigationPointHeightFactor property to determine how far from the bottom of the display the location will be anchored. |
| Compass Navigation | Good for walking. The map view updates for the current location, but orients to the direction the device is pointing. |
When you manipulate the map view's area of interest either programmatically or by panning/zooming it, the auto-pan mode will be reset to off. You can monitor for changes to the auto-pan mode with the AGSLocationDisplay.autoPanModeChangeHandler.
When you switch on auto-pan (i.e. it was off, but you set it to one of the other values), the map view will pan and zoom to the next location update. You can control the scale level for this pan and zoom with AGSLocationDisplay.initialZoomScale.
In most use cases, fixing the zoom like this is sensible behavior, but if you want to just recenter without zooming the map, simply set the initialZoomScale to the current AGSMapView.mapScale before you set the autoPanMode.
Configuring appearance
By default the location symbol will be a blue dot. It's augmented with a few visual aids to indicate accuracy, direction of motion (course), direction the device is pointing (heading) and whether locations are being updated (a "ping"). See these properties on AGSLocationDisplay for more details:
| The Location… | Gathering the Location… |
|---|---|
You control whether to use the courseSymbol when movement is detected with the AGSLocationDisplay.useCourseSymbolOnMovement property.
Lastly, if you don't want a visual indication that a new location was received, you can set AGSLocationDisplay.showPingAnimation to false.
Location Data Source
One other important configurable item on AGSLocationDisplay is the location data source. We'll look at that part 2 when I'll cover how data sources work, and in part 3 we'll create our own custom data source.