Set up a map

Select platform: Android iOS

To follow a trip in your consumer app, you first need to define a map and add support for vector maps, if needed.

To set up a map in your app, follow these steps:

  1. Define a map fragment to follow a trip.
  2. Add support for a maps base layer and view controller.
  3. Add support for Android vector graphics to display vector maps, if needed.

After you've defined a map, you can add additional views and camera controls you want to customize the visual experience. For more details, see Style a map.

Step 1: Define a map fragment to follow a trip

You define a map by adding a map fragment or view to create the map where you share an on-demand trip in your consumer app. To define your map, follow one of these methods:

  • ConsumerMapFragment: Use to define your map with a Fragment.

  • ConsumerMapView: Use to define a map with a View.

The features are the same for either method, so choose which method is better for your application.

Both methods are explained in more detail in the following section.

Add a map fragment or view

To create a map to display trip progress using either an Android fragment or a view, follow these steps and refer to the code examples.

  1. Define a fragment or view in your application layout XML file located in /res/layout. Define the trip map as either a fragment using ConsumerMapFragment, or as a view using ConsumerMapView.

    The fragment or view then provides access to the trip map that your app can access and modify. The map also provides a handle to the ConsumerController, which allows your app to control and customize the consumer experience.

  2. From your onCreate() method, call getConsumerGoogleMapAsync(callback), which returns the ConsumerGoogleMap asynchronously in the callback.

  3. Use the ConsumerGoogleMap to display trip progress and update as needed.

Example of how to add ConsumerMapFragment

  1. Define the fragment in your application layout XML file, as shown in the following code example.

    <fragment
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:name="com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapFragment"
    android:id="@+id/consumer_map_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

  2. Make a call to getConsumerGoogleMapAsync() from the onCreate() method.

Java

 public class SampleAppActivity extends AppCompatActivity {

   @Override
   protected void onCreate(Bundle savedInstanceState) {

     // Find the ConsumerMapFragment.
     ConsumerMapFragment consumerMapFragment =
         (ConsumerMapFragment) fragmentManager.findFragmentById(R.id.consumer_map_fragment);

     // Initiate the callback that returns the map.
     if (consumerMapFragment != null) {
       consumerMapFragment.getConsumerGoogleMapAsync(
           new ConsumerMapReadyCallback() {
             // The map returned in the callback is used to access the ConsumerController.
             @Override
             public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
               ConsumerController consumerController = consumerGoogleMap.getConsumerController();
             }
           });
     }
   }

 }

Kotlin

 class SampleAppActivity : AppCompatActivity() {
   override fun onCreate(savedInstanceState: Bundle?) {
     // Find the ConsumerMapFragment.
     val consumerMapFragment =
       fragmentManager.findFragmentById(R.id.consumer_map_fragment) as ConsumerMapFragment

     consumerMapFragment.getConsumerGoogleMapAsync(
       object : ConsumerMapReadyCallback() {
         override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
           val consumerController = consumerGoogleMap.getConsumerController()!!
         }
       }
     )
   }
 }

Example of how to add ConsumerMapView

  1. Use the view either in a fragment or in an activity, as defined in your XML file.

     <com.google.android.libraries.mapsplatform.transportation.consumer.view.ConsumerMapView
     xmlns:android="http://schemas.android.com/apk/res/android"
     android:id="@+id/consumer_map_view"
     android:layout_width="match_parent"
     android:layout_height="match_parent" />

  2. Make the call to getConsumerGoogleMapAsync() from onCreate(). In addition to the callback parameter, include the following details:

    • The containing activity or fragment. The activity or fragment base class must be either a FragmentActivity or a support Fragment (respectively), since they provide access to its lifecycle.

    • GoogleMapOptions (which can be null), containing configuration attributes for the MapView.

Java

public class SampleAppActivity extends AppCompatActivity {

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    ConsumerMapView mapView = findViewById(R.id.consumer_map_view);

    if (mapView != null) {
      mapView.getConsumerGoogleMapAsync(
          new ConsumerMapReadyCallback() {
            // The map returned in the callback is used to access the ConsumerController.
            @Override
            public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerGoogleMap) {
              ConsumerController consumerController = consumerGoogleMap.getConsumerController();
            }
          }, this, null);
    }
  }

}

Kotlin

class SampleAppActivity : AppCompatActivity() {
  override fun onCreate(savedInstanceState: Bundle?) {
    val mapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

    mapView.getConsumerGoogleMapAsync(
      object : ConsumerMapReadyCallback() {
        // The map returned in the callback is used to access the ConsumerController.
        override fun onConsumerMapReady(consumerGoogleMap: ConsumerGoogleMap) {
          val consumerController = consumerGoogleMap.getConsumerController()!!
        }
      },
      /* fragmentActivity= */ this,
      /* googleMapOptions= */ null,
    )
  }
}

A MapView in a fragment is the same as for the preceding example for MapView in an activity, except that the fragment inflates the layout that includes the MapView in the fragment onCreateView() method.

Java

public class MapViewInFragment extends Fragment {

  @Override
  public View onCreateView(
      @NonNull LayoutInflater layoutInflater,
      @Nullable ViewGroup viewGroup,
      @Nullable Bundle bundle) {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false);
  }

}

Kotlin

class MapViewInFragment : Fragment() {
  override fun onCreateView(
    layoutInflater: LayoutInflater,
    container: ViewGroup?,
    savedInstanceState: Bundle?,
  ): View {
    return layoutInflater.inflate(R.layout.consumer_map_view, viewGroup, false)
  }
}

Step 2: Add support for a maps base layer and view controller

To share trip progress in your app, add the following classes to your app: ConsumerGoogleMap and ConsumerController.

  • Get ConsumerGoogleMap from either ConsumerMapFragment or ConsumerMapView, both of which asynchronously return ConsumerGoogleMap in ConsumerMapReadyCallback.

    ConsumerGoogleMap is a wrapper class for the GoogleMap class. It uses an API equivalent to GoogleMap so that your app can interact with the map. In this way, your app can interact seamlessly with the same underlying Google map. For example, GoogleMap only allows a single callback registration, but ConsumerGoogleMap supports dual registered callbacks. These callbacks let your app register callbacks that are called sequentially.

  • Get ConsumerController from ConsumerGoogleMap in getConsumerController().

    ConsumerController provides access to trip sharing features such as monitor trips, control trip status, and set locations.

For how to add ConsumerGoogleMap and ConsumerController to your app in Java and Kotlin, see the following examples.

Java

private ConsumerGoogleMap consumerGoogleMap;
private ConsumerController consumerController;
private ConsumerMapView consumerMapView;

consumerMapView.getConsumerGoogleMapAsync(
    new ConsumerMapReadyCallback() {
      @Override
      public void onConsumerMapReady(@NonNull ConsumerGoogleMap consumerMap) {
        consumerGoogleMap = consumerMap;
        consumerController = consumerMap.getConsumerController();
      }
    },
    this, null);

Kotlin

var consumerGoogleMap: ConsumerGoogleMap
var consumerController: ConsumerController
val consumerMapView = findViewById(R.id.consumer_map_view) as ConsumerMapView

consumerMapView.getConsumerGoogleMapAsync(
  object : ConsumerMapReadyCallback() {
    override fun onConsumerMapReady(consumerMap: ConsumerGoogleMap) {
      consumerGoogleMap = consumerMap
      consumerController = consumerMap.getConsumerController()
    },
    /* fragmentActivity= */ this,
    /* googleMapOptions= */ null,
  }
)

Step 3: Add support for Android vector graphics

If your app design requires support for vector graphics, then add support for Android devices and vector drawables using these steps:

  1. Add the following code to your Activity. This codes extends AppCompatActivity to use the Vector drawables in the Consumer SDK.

Java

// ...
import android.support.v7.app.AppCompatActivity;

// ...

public class ConsumerTestActivity extends AppCompatActivity {
  // ...
}

Kotlin

// ...
import android.support.v7.app.AppCompatActivity

// ...

class ConsumerTestActivity : AppCompatActivity() {
  // ...
}

What's Next

Follow a trip in Android Style a map