Blue Dot
Displaying the Blue Dot on a map to indicate a user's location is a common requirement for mapping applications. The Mappedin Web SDK provides a simple way to add a Blue Dot to a map.
Enable & Disable Blue Dot
With Mappedin Web SDK, an app can display a user's location by calling MapView.BlueDot.enable(). This will display a prompt for the user to allow or deny sharing their location with the web page. If permission is given, a device's geolocation is displayed on the map as a Blue Dot. The enable
method accepts a TBlueDotOptions object as a parameter, which can be used to change the color of the Blue Dot, accuracy shading and heading indicator. It also allows a developer to enable Blue Dot debug logging, set the size of the Blue Dot, indicate whether it should watch the browser's geolocation for updates and to set the timeout value used to set the Blue Dot to inactive after a period of no location updates.
When no longer required, the Blue Dot can be disabled using MapView.BlueDot.disable().
The following example demonstrates how to enable the Blue Dot, setting TBlueDotOptions parameters to customize the colors of the Blue Dot, set its timeout to 20 seconds and enable debug logging.
mapView.BlueDot.enable({
color: 'tomato',
debug: true,
accuracyRing: {
color: 'forestgreen',
opacity: 0.1,
},
heading: {
color: 'aqua',
opacity: 1,
},
inactiveColor: 'wheat',
timeout: 20000,
});
Blue Dot States
The Blue Dot has a number of visual states that are used to convey information to the user.
-
When the Blue Dot position given to the Mappedin Web SDK has a high accuracy (accuracy value of 0), it is displayed as bright blue.
-
A semi-transparent blue shadow is displayed underneath the Blue Dot to indicate accuracy range in meters.
-
A heading can be shown to indicate the direction the user is facing.
-
After the TBlueDotOptions.timeout has passed (default of 30 seconds), the Blue Dot is displayed as greyed. This indicates the user may have moved while no updates were received.
Blue Dot Example App
Experiment with all Blue Dot states using the CodeSandbox below.
Indoor Positioning
Mappedin Web SDK can use the browser's Geolocation API for position updates and display a Blue Dot on the map based on the given location. For indoor environments, an indoor positioning system may be required to provide an accurate location because satelite based positioning is not available indoors and cellular based positioning may not be accurate enough for indoor navigation.
The Mappedin Web SDK can use the location provided from an indoor positioning system to display the Blue Dot. An example of an indoor positioning system is the Apple Maps Program, which provides a location service for indoor use. A Mappedin Map can be exported to IMDF format and imported into the Apple Maps Program. For more information refer to the Mappedin IMDF Export Page.
For development purposes, indoor positions can be simulated using Chrome Developer Tools or by using pre-generated location data. The MapView.BlueDot.update() method can be used to update the Blue Dot's position on the map. It accepts a TBlueDotPositionUpdate that can set the latitude
, longitude
, accuracy
heading
and floorOrFloorId
of the Blue Dot. All parameters of TBlueDotPositionUpdate
are required, however it is possible to set individual parameters to override one or more coming from the browser's geolocation API. To do so provide values for parameters the app wishes to override and use device
as the value of those parameters that should not be overridden. For example an app may wish to use the browser's Device Orientation API to provide the heading of the Blue Dot and leave the latitude and longitude to be provided by the browser's geolocation API.
The following JSON object represents a TBlueDotPositionUpdate that overrides heading
and uses the browser's geolocation API for the remaining parameters.
{
"accuracy": 'device',
"floorOrFloorId": 'device',
"latitude": 'device',
"longitude": 'device',
"heading": 90
}
Blue Dot Events
Blue Dot fires events that can be used to respond to changes to its position, state and errors. The data structure of these events are defined in TBlueDotEvents. The following events are available:
blue-dot-position-update
: Fired when Blue Dot's position is updated.blue-dot-state-change
: Fired when Blue Dot's state changes.blue-dot-error
: Fired when an error occurs.
Blue Dot Position Update
The blue-dot-position-update
event is fired when the Blue Dot's position is updated. It provides the coordinate, floor, accuracy and heading from the last position update.
mapView.on('blue-dot-position-update', (e) => {
console.log('blue-dot-position-update', e.coordinate, e.floor, e.accuracy, e.heading);
});
Blue Dot State Change
The blue-dot-state-change
event is fired when Blue Dot state changes. It provides the new state of the Blue Dot and the action that caused the state change. Actions are defined in TBlueDotAction and states in TBlueDotState. The states pertain to how the Blue Dot is displayed on the map. Refer to the Blue Dot States section above for images of each state.
mapView.on('blue-dot-state-change', (e) => {
console.warn('blue-dot-state-change', e.state, e.action);
});
Blue Dot Error
The blue-dot-error
event is fired when an error occurs. It provides the error as a GeolocationPositionError object.
mapView.on('blue-dot-error', (e) => {
console.error('blue-dot-error', e);
});
Generating Test Location Data
The Mappedin Blue Dot Faker app can be used to generate location data for testing. To create test data, load a map in the Faker app and choose a Start and End space. Click Generate to generate the data and observe the Blue Dot on the map using the generated data for its position. Press the Download button to download the location data in JSON format. The data can be customized by specifying jitter
, accuracy
and time between updates
:
- Jitter: The amount of random variation in the position data from the navigation path.
- Accuracy: The accuracy used in the data. In a real world scenario this value represents how accuract the indoor positioning system believes the result to be and is used to draw the light blue shading around the Blue Dot.
- Time between updates: The time between each position update can be used to control the speed of the Blue Dot's movements.