Maps SDK for Android
Overview

Showing device location

Showing the user's current location as a map annotation is a popular and often critical feature of location-based apps. The Maps SDK's LocationComponent makes use of the Maps SDK's runtime styling capabilities to display the device location icon within the map itself rather than on top as a simple Android view. Mapbox map layers and layer styling give you precise control, if you want it, of the way that a device's location is shown on the map.

help
Note

This LocationComponent has replaced the now-deprecated Location Layer Plugin. The LocationComponent is integrated into the Maps SDK for Android so that you don't need to add additional dependencies. It brings the same set of functionality that you were used to with the plugin, as well as additional bug fixes.

Activating

Retrieving and activating the LocationComponent are the first two steps towards showing the device's location on a Mapbox map.

MapboxMap#getLocationComponent() fetches the component and LocationComponent#activateLocationComponent() activates it. Both need to be called before any other LocationComponent adjustments, such as its visibility, are performed.

@Override
public void onMapReady(MapboxMap mapboxMap) {
LocationComponent locationComponent = mapboxMap.getLocationComponent();
locationComponent.activateLocationComponent(this);
}

Visibility

There is a single method to either enable or disable the LocationComponent's visibility after activation. The setLocationComponentEnabled() method requires a true/false boolean parameter. When set to false, this method will hide the device location icon and cease map camera animations from occurring.

locationComponent.setLocationComponentEnabled(true);

Customization

The LocationComponent allows for several customizations. You can set the drawables, opacities, colors, and more. Create a LocationComponentOptions object and then use whichever methods you'd like. Then use the object either while activating the component or by passing it through as a parameter of the LocationComponent#applyStyle() method at a later time.

See all the attributes that can be customized via the LocationComponent's methods in the full list of attributes and styles that are part of the public API.

@Override
public void onMapReady(MapboxMap mapboxMap) {
LocationComponentOptions options = LocationComponentOptions.builder(this)
.layerBelow(layerId)
.foregroundDrawable(R.drawable.drawable_name)
.bearingTintColor(int color)
.accuracyAlpha(float)
.build();
locationComponent = mapboxMap.getLocationComponent();
locationComponent.activateLocationComponent(this, options);
}

RenderMode

The RenderMode class contains preset options for the device location image.

locationComponent.setRenderMode(RenderMode.NORMAL);

There are three types of RenderMode options:

RenderModeDescription
NORMALThis mode shows the device location, ignoring both compass and GPS bearing (no arrow rendered).
COMPASSThis mode shows the device location, as well as an arrow that is considering the compass of the device.
GPSThis mode shows the device location with the icon bearing updated from the Location updates being provided to the LocationComponent.
help
Note

The actual device location icon is highly customizable with methods such as LocationComponentOptions#foregroundDrawable() and LocationComponentOptions#backgroundDrawable().

CameraMode

The method LocationComponent#setCameraMode(@CameraMode.Mode int cameraMode) allows developers to set specific camera tracking instructions as the device location changes.

locationComponent.setCameraMode(CameraMode.TRACKING);

There are currently 7 CameraMode options available:

CameraModeDescription
NONENo camera tracking.
NONE_COMPASSCamera does not track location, but does track compass bearing.
NONE_GPSCamera does not track location, but does track GPS Location bearing.
TRACKINGCamera tracks the device location, no bearing is considered.
TRACKING_COMPASSCamera tracks the device location, tracking bearing provided by the device compass.
TRACKING_GPSCamera tracks the device location, with bearing provided by a normalized Location#getBearing().
TRACKING_GPS_NORTHCamera tracks the device location, with bearing always set to north (0).

Here are a few examples from the LocationModesActivity in the Maps SDK's test application:

CameraMode.NORMAL

CameraMode.COMPASS

CameraMode.GPS

Traditional camera transitions will be canceled when any of the camera modes, besides CameraMode#NONE, are engaged. Use LocationComponent#zoomWhileTracking and LocationComponent#tiltWhileTracking to manipulate the camera in a tracking state. Use these two in combination with traditional camera transitions and MapboxMap#CancelableCallback to schedule fluid transitions.

When instantiating the LocationComponent for the first time, the map's max/min zoom levels will be set toLocationComponentOptions#MAX_ZOOM_DEFAULT and LocationComponentOptions#MIN_ZOOM_DEFAULT respectively. Adjust the zoom range with the LocationComponentOptions#maxZoom() and LocationComponentOptions#minZoom() methods in the LocationComponentOptions class.

Gesture thresholds while camera tracking

The LocationComponent is integrated with the Mapbox Gestures for Android library. The component will adjust the camera's focal point and increase thresholds to enable camera manipulation, like zooming in and out, without breaking tracking. Enabling this feature is explicitly opt-in because it overwrites custom gestures detection implementation set with MapboxMap#setGesturesManager(AndroidGesturesManager, boolean, boolean).

To enable the feature use LocationComponentOptions#trackingGesturesManagement(boolean).

You can adjust thresholds that need to be exceeded in order to break the tracking for one pointer gestures (like panning the map, double-tap to zoom in) and multi-pointer gestures (like scale gesture, two-tap to zoom out):

  • LocationComponentOptions#trackingInitialMoveThreshold(float) adjusts the minimum single pointer movement in pixels required to break camera tracking.
  • LocationComponentOptions#trackingMultiFingerMoveThreshold(float) adjusts minimum multi pointer movement in pixels required to break camera tracking (for example during scale gesture).
  • If either of these thresholds are exceeded and tracking is dismissed, developers can listen to this with a OnCameraTrackingChangedListener:
LocationComponent locationComponent = mapboxMap.getLocationComponent();
locationComponent.addOnCameraTrackingChangedListener(new OnCameraTrackingChangedListener() {
@Override
public void onCameraTrackingDismissed() {
// Tracking has been dismissed
}
@Override
public void onCameraTrackingChanged(int currentMode) {
// CameraMode has been updated
}
});