User's location on the map
The Mapbox Maps SDK for Android's location component enables your application to observe, respond and display the user's location.
Before you can show the user's location on the map, users must grant your application permission to access their location. See previous section Permission handling for more details.
Location component
To visualize the user's location on the map you should enable the location component. There are different ways to enable location:
- Directly in your
MapView
XML component using the attributemapbox_locationComponentEnabled
:
<com.mapbox.maps.MapView
android:id="@+id/mapView"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:mapbox_locationComponentEnabled="true"
app:mapbox_locationComponentPuckBearing="heading" />
- Programmatically, by calling
enabled
through the location component:
The location component makes use of two dedicated layers in the Maps SDK to display either a 2D device location icon (using layer ID LOCATION_INDICATOR_LAYER
) or a 3D model (using layer ID MODEL_LAYER
). These layers are displayed within the map rather than on top of the map as an Android view. Layers in Mapbox map styles give you precise control over how you show a device's location on the map.
By default, the Maps SDK for Android provides a two dimensional location puck with a blue dot and white circle.
Show the user's location on a map using the default location puck.
Puck style options
There are several options to customize the appearance of the location puck. You can see the full list at LocationComponentSettings
.
You can directly use the LocationComponentPlugin
to change the settings. For example, the pulsing effect is disabled by default, but you can enable this effect by passing true
to the pulsingEnabled
property.
Use a custom image
You can further customize the puck by using custom image drawables to display the user's location on a map. Set custom location puck styles in one of two ways: using XML attributes or programmatically using the LocationPuck
class.
Here's an example using style XML attributes to customize the appearance of the location icon:
<com.mapbox.maps.MapView
android:id="@+id/mapView"
android:layout_width="match_parent"
android:layout_height="match_parent"
app:mapbox_locationComponentEnabled = "true"
app:mapbox_locationComponentLocationPuck= "location_puck_2_d"
app:mapbox_locationComponentLocationPuckLocationPuck2DTopImage= "@drawable/custom_user_icon"
app:mapbox_locationComponentLocationPuckLocationPuck2DBearingImage= "@drawable/custom_user_arrow"
app:mapbox_locationComponentLocationPuckLocationPuck2DShadowImage= "@drawable/custom_user_puck_icon"
tools:context=".examples.LocationComponentActivity" />
Here's an example using the LocationPuck
class to programmatically customize the appearance of the location icon. Create a LocationPuck2D
or LocationPuck3D
object and set it through LocationComponentPlugin#locationPuck
method. The following example also specifies the size of the icon based on the map's zoom level using scaleExpression
.
You can revert to the default 2D puck using createDefault2DPuck
function.
Set Puck Bearing Source
The user location can track bearing using the device heading or device course. This option is in LocationComponentSettings
.
Example
mapView.location.puckBearing = PuckBearing.HEADING
mapView.location.puckBearing = PuckBearing.COURSE
Location Tracking
To make the camera follow the location puck, you can use ViewportPlugin
, which is available at mapView.viewport
.
ViewportPlugin
is primarily used to track objects on a map, but it can be extended with custom states and transitions as well.
Viewport States
ViewportState
produces camera updates based on implementation-specific rules (For example: tracking a dynamic location data source or showing a static overview of a predefined region).
Two ViewportState
implementations are provided by the SDK, both of which can be instantiated from the ViewportPlugin
:
viewport.makeFollowPuckViewportState(options)
: This state syncs the map camera with the location puck.viewport.makeOverviewViewportState(options)
: This state makes the camera show a user-provided geometry.
Besides using these built-in implementations, you can also create your own and use them with the ViewportPlugin
.