Integrate map support in Android applications based on MapBox

one, Introduction

MapBox is an open source vector map SDK. The promise of this framework is to provide quality rendering speed and smoothness in developing video games. If you are interested in integrating mapping capabilities into your application, then MapBox is one of the options worth considering.

2. Permission Settings

First of all, you can download the source code provided in this article from GitHub at https://github.com/sitepoint-editors/MapBox-App.

To use Mapbox in your application, you need an API access token. To do this, you need to create a Mapbox account first, which you can find at https://www.mapbox.com/studio/account/tokens.

Then, add the token to your Android app's strings.xml file:

 < string   name = "accessToken" > Your access token </ string >  

Next, add the following Internet and location permissions to the AndroidManifest.xml configuration file:

 < uses-permission   android:name = "android.permission.ACCESS_NETWORK_STATE" />    
 < uses-permission   android:name = "android.permission.INTERNET" />     
 < uses-permission   android:name = "android.permission.ACCESS_COARSE_LOCATION" />  
 < uses-permission   android:name = "android.permission.ACCESS_FINE_LOCATION" />  
 < uses-permission   android:name = "android.permission.ACCESS_WIFI_STATE" />  

Please note: The above permissions are required at runtime on Android Marshmallow (API 23) and higher.

3. Install MapBox

Next, open the build.gradle configuration file (the one under the Module: app folder) and add a dependency on MapBox. Please refer to the configuration code as shown below:

 repositories {
 mavenCentral()  
 }
 dependencies {
 . . .   
    compile('com.mapbox.mapboxsdk:mapbox-android-sdk:3.2.0@aar') {
 transitive = true  
 }
    compile ('com.mapbox.mapboxsdk:mapbox-android-directions:1.0.0@aar'){  
 transitive = true  
 }
 }

The first configuration in the code above describes Mapbox. The following configuration corresponds to the Directions library description, which is used to provide driving, walking, and biking functions to the application and support drawing their whereabouts on the map.

4. MapBox Layout

Next, open the layout file content_main.xml and replace the original content with the following:

 <? xml   version = "1.0"   encoding = "utf-8" ?>  
 < RelativeLayout   xmlns:android = "http://schemas.android.com/apk/res/android"  
 xmlns:mapbox = "http://schemas.android.com/apk/res-auto"  
 xmlns:tools = "http://schemas.android.com/tools"  
 android:layout_width = "match_parent"  
 android:layout_height = "match_parent"  
 tools:context = "com.example.valdio.mapboxintegration.MainActivity"  
 tools:showIn = "@layout/activity_main" >  
 < com.mapbox.mapboxsdk.views.MapView  
 android:id = "@+id/mapview"  
 android:layout_width = "fill_parent"  
 android:layout_height = "fill_parent"  
 mapbox:access_token = "@string/accessToken"   />  
 </RelativeLayout>​​  

Next, initialize the variables you will need to use in the MainActivity file:

 public class MainActivity extends AppCompatActivity {
  private MapView mapView = null ;
  private String MAPBOX_ACCESS_TOKEN = "" ;
  private DirectionsRoute currentRoute = null ;
 ...

Next, in the MainActivity.java file, delete the code that creates the toolbar and floating button in the onCreate() method and add the following code to initialize the map:

 String MAPBOX_ACCESS_TOKEN = getResources ().getString(R.string.accessToken);
 // Set up a standard Mapbox map
 MapView mapView = (MapView) findViewById(R.id.mapview);
 mapView.setAccessToken(MAPBOX_ACCESS_TOKEN);  
 mapView.setStyleUrl(Style.MAPBOX_STREETS); // specify the map style  
 mapView.setZoom(14); // zoom level  
 mapView.onCreate(savedInstanceState);

Mapbox requires the implementation of the Activity's lifecycle methods to avoid runtime errors; therefore, you need to add the following override function:

 @Override  
 protected void onStart() {  
 super.onStart();  
 mapView.onStart();  
 }
 @Override
 protected void onStop() {  
 super.onStop();  
 mapView.onStop();  
 }
 @Override  
 protected void onDestroy() {
 super.onDestroy();  
 mapView.onDestroy();  
 }  
 @Override  
 protected void onResume() {
 super.onResume();
 mapView.onResume();
 }
 @Override
 protected void onPause() {  
 super.onPause();
 mapView.onPause();  
 }  
 @Override
 protected void onSaveInstanceState(Bundle outState) {  
    super.onSaveInstanceState(outState);
    mapView.onSaveInstanceState(outState);
 }

OK. Now that Mapbox is configured, it's time to build the application.

5. Add markers to the map

Now, add the following code to the top of the onCreate method of MainActivity:

 @Override
 protected void onStart() {
 super.onStart();
 mapView.onStart();
 }
 @Override  
 protected void onStop() {
 super.onStop();
 mapView.onStop();
 }
 @Override
 protected void onDestroy() {
 super.onDestroy();
 mapView.onDestroy();
 }
 @Override
 protected void onResume() {  
 super.onResume();  
 mapView.onResume();  
 }  
 @Override  
 protected void onPause() {  
 super.onPause();
 mapView.onPause();  
 }  
 @Override  
 protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);  
    mapView.onSaveInstanceState(outState);  
 }

The CameraPosition in this code is a very useful Mapbox class that can be used to set the position, angle, zoom, tilt, and other information of the user's view.

So far, our map looks like this:

6. Get device location

In order for Mapbox to access your location information, your location services must be enabled and your app should have permissions to use them. As mentioned above, these permissions are required at runtime on Android Marshmallow (API 23) and later.

Now, let's create a new function and add the code to get the current position:

 private void myLocation() {
        if (ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED && ActivityCompat.checkSelfPermission(this, Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
            // TODO: Consider calling  
            // ActivityCompat#requestPermissions  
            // here to request the missing permissions, and then overriding  
            // public void onRequestPermissionsResult(int requestCode, String[] permissions,  
            // int[] grantResults)  
            // to handle the case where the user grants the permission. See the documentation  
            // for ActivityCompat#requestPermissions for more details.  
 return;  
 }
        mapView.setMyLocationEnabled(true);
        mapView.setMyLocationTrackingMode(MyLocationTracking.TRACKING_FOLLOW);  
        mapView.getMyLocation();  
 }

Then, add the following function call after the map initialization code:

 ...  
 mapView.onCreate(savedInstanceState);  
 myLocation();

In this case, we set the tracking mode to TRACKING_FOLLOW, which means that the user's location will be continuously monitored and the map will be continuously updated as changes occur.

7. Draw a route on the map

Now that we have created our markers and locations, it's time to draw our routes on the map.

This uses the second library (Directions library) imported earlier in the dependency settings, which is also developed by the Mapbox team.

Here's how it works:

1. Create two waypoint locations, one for the departure point and one for the destination.

2. Create a MapboxDirections generator object to make a network request to the Mapbox API with the waypoint location information corresponding to the starting and destination points, as well as configuration information about the directions (driving, walking, biking, etc.).

3. Asynchronously execute direction requests. The MapboxDirections class provides a built-in asynchronous request using the Retrofit API. Specifically, the enqueue() function is used to execute the request.

4. The OnResponse() method returns the Retrofit response result, which is a standard JSON API response.

5. The response body contains the location coordinates, which will be plotted on the map later.

6. Use the Mapbox Polyline function to draw the coordinates on the map. A polyline is a geometric feature that forms an open polyline by connecting multiple line segments end to end.

To use the Direction library, we need to get the device's location as the origin waypoint, and the location information of the destination waypoint specified by the user through a long press.

8. Add waypoint locations and add markers at the destination

Now, add the following code to the top of the onCreate method:

 mapView.setOnMapLongClickListener(new MapView.OnMapLongClickListener() {  
 @Override  
    public void onMapLongClick(LatLng point) {  
        //Remove previously added markers  
        //Marker is an annotation that shows an icon image at a geographical location  
        //so all markers can be removed with the removeAllAnnotations() method. 
         mapView.removeAllAnnotations();  
        // Set the origin waypoint to the devices location  
        Waypoint origin = new Waypoint(mapView.getMyLocation().getLongitude(), mapView.getMyLocation().getLatitude());  
        // Set the destination waypoint to the location point long clicked by the user  
        Waypoint destination = new Waypoint(point.getLongitude(), point.getLatitude());  
        // Add marker to the destination waypoint  
        mapView.addMarker(new MarkerOptions()  
                .position(new LatLng(point))  
                .title("Destination Marker")
                .snippet("My destination"));
 // Get route from API
        getRoute(origin, destination); } 
 
 });

9. Create a MapboxDirections network request and run it asynchronously

Next, create a method as shown below to obtain *** routing information:

 private void getRoute(Waypoint origin, Waypoint destination) {
  MapboxDirections directions = new MapboxDirections.Builder()  
          .setAccessToken(MAPBOX_ACCESS_TOKEN)
 .setOrigin(origin)
          .setDestination(destination)  
          .setProfile(DirectionsCriteria.PROFILE_WALKING)  
 .build();  
  directions.enqueue(new Callback < DirectionsResponse > () {  
 @Override  
      public void onResponse(Response < DirectionsResponse > response, Retrofit retrofit) {  
          // Display some info about the route  
 currentRoute = response .body().getRoutes().get(0);
          showToastMessage(String.format("You are %d meters \nfrom your destination", currentRoute.getDistance()));     
          // Draw the route on the map  
          drawRoute(currentRoute);  
 }
 @Override  
      public void onFailure(Throwable t) {
          showToastMessage("Error: " + t.getMessage());  
 }  
 });  
 }

10. Draw a polyline using coordinate points on the map

Add the following method to implement route drawing:

 private void drawRoute(DirectionsRoute route) {  
  // Convert List < Waypoint > into LatLng[]  
 List <Waypoint>​   waypoints = route .getGeometry().getWaypoints();  
  LatLng[] point = new LatLng[waypoints.size()];  
 for (int i = 0 ; i <   waypoints.size (); i++) {  
 point[i] = new LatLng(  
              waypoints.get(i).getLatitude(),  
              waypoints.get(i).getLongitude());  
 } 
  // Draw Points on MapView  
  mapView.addPolyline(new PolylineOptions()  
 .add(point)  
          .color(Color.parseColor("#38afea"))  
 .width(5));  
 }
 private void showToastMessage(String message) {  
  Toast.makeText(this, message, Toast.LENGTH_SHORT).show();  
 }

OK, now run your project. Select two points on the map and you will see something similar to the following:

11. Summary

In this article, we introduced the basics of using the MapBox SDK and its Directory library. In fact, MapBox has much more and richer content that can be applied to your program, such as different map styles, customized vector map drawing, and so on.

As a supplement to this article, I also recommend another library Geocoding (https://github.com/mapbox/mapbox-geocoder-android). This library can convert coordinate information into a map, or vice versa. Of course, to learn more about MapBox, it is recommended to study its mobile application examples (https://www.mapbox.com/mobile/). You will find more libraries available at this URL.