Last week we released version 4.0.0 of our Android SDK with support for MapboxMap, a new object that improves testability, compatibility and configurability.

How MapboxMap works

With 4.0.0 we have changed the interaction model, pushed an MVC design, and introduced a controller class called MapboxMap. This allowed us to move all the interaction logic from the MapView class to transfer the control to the MapboxMap.

In practice, you can get a reference to a MapboxMap via the OnMapReadyCallback callback:

mapView.getMapAsync(new OnMapReadyCallback() {
    public void onMapReady(MapboxMap mapboxMap) {
        // Add markers, polylines, etc.

Both the MapView and the MapFragment expose the getMapAsync() method.


Having a MapboxMap class separate from MapView improves testability by making it possible to write local JVM unit tests and mock the MapView object, resolving a previously difficult unit testing scenario.

This new approach allows us to run unit tests on every push and validate with each pull request to protect the code from regressions. Visit our testing documentation for details on how we’re doing this.


MapboxMap improves compatibility with the Google Maps Android SDK, streamlining code migration. Key classes like CameraUpdateFactory, MapFragment, MapView, OnMapReadyCallback, SupportMapFragment, or VisibleRegion are now on par with the Google Maps equivalent.

For example, in the past developers had trouble porting camera position logic over to our older SDK:

mapView = (MapView) findViewById(;
mapView.setCentreCoordinate(new LatLng());

With the push for compatibility the code now follows the Google Maps conventions. You only need to change GoogleMap with MapboxMap:

mapView = (MapView) findViewById(;
mapView.getMapAsync(new OnMapReadyCallback() {
    public void onMapReady(MapboxMap mapboxMap) {
      mapboxMap.animateCamera(CameraUpdateFactory.newCameraPosition(new CameraPosition.Builder()
          .target(new LatLng())


The 4.0 release also changed the way the onMapReady callback behaves. This lets you configure map attributes as early as possible to make sure your style is loaded promptly and the camera is positioned correctly.

You can do this via XML:

    mapbox:access_token="your access token here"

Or programmatically through MapboxMapOptions. If you are using a MapFragment you can pass these options in using the static factory method newInstance(MapboxMapOptions). If you are using a MapView, you can pass these options in using the constructor MapView(Context, MapboxMapOptions).

Use MapboxMap today

Start building your apps today with the new Android SDK. Make sure to check our Javadoc for all the implementation details.