In the first part of this tutorial I will show you can start using Google Maps Android API v2 in your Android application. The goal is to create a skeleton project that
is capable of displaying a map using the new Google Map for Android API v2
uses ActionBarSherlock.
can run on older versions of Android (2.x and up).
I’ve also created a screencast that covers setting up a skeleton project (not covering ActionBarSherlock).
Google Maps Android API v2
The new Google Maps Android API v2 (available through Google Play Services) is a vast improvement over the original one and comes with many new features. Not only does it really stand out from a UI perspective but also on an API level can the new Maps v2 library be considered a “delight” for both end-users and developers.
Before the Google Maps Android API v2 was released, developers were forced to embed a MapView component in a special type of Activity called a MapActivity.
When developers created map applications using the MapView component, the maps embedded in these third party applications were not of the same standard as the ones that you found on the Google Maps application. Not only were the tiles of much higher quality in the Google Maps application, but subtle differences like auto-orienting street-names and labels that were present in the Google Maps application were not available in the MapView component. So effectivly, developers were left with a lower quality map component.
The MapView component also had several limitations. You could use 1 MapView component in your application and there was no Fragment support.
This has all changes with the new Google Maps Android v2 API.
A quick overview of the features of the new Maps Android API v2:
Distribution via Google Play Services (no more waiting for Android platform updates to get new functionality)
Full fragment support (no more MapView, no more single map / app limitation)
New Map look and feel (new tiles, new gestures, 3D support ….)
In the first part of this series I will show you how to
setup the skeleton project
install the library projecs
setup your map key
add the map to your application.
have it run on lower Android SDK levels
add ActionBarSherlock
Setting up the skeleton project.
I’m going to be using Eclipse ADT 22 to build the project. We’ll start by creating a standard Android project using the project wizard.
Our project is going to use the following Android libraries
the new Google Maps Android API v2
ActionBarSherlock library
Please checkout the resources at the end of the document on how to obtain these projects.
Installing the library projects.
The first thing we need to do is retrieve the library projects.
Google Play Services
ActionBarSherlock
Google Play Services can be downloaded using the android SDK Manager. Navigate to the Extras folder and select Google Play Services.
Google Play Services will be extracted in sdk/extras/google/google_play_services)
Note: When importing Library projects into your Eclipse workspace, it’s safer to have them somewhere outside of the current workspace before importing them. Otherwise, you might run into the following error :
To workaround this problem make sure that before importing the project(s) you simply put them in a location outside of your current workspace, and while importing select the Copy projects into workspce option if you want to have them in your workspace folder.
We are going to add the library projects into our Eclipse workspace by importing them. Browse to the Google Play Services path in the SDK and import the project.
Do the same for ActionBarSherlock. Once both projects compile in your workspace, you can start adding these library projects as dependencies to our project.
ADT 22 Android Private Libraries
There’s an issue with ADT 22 that it sometimes “forgets” to export the libraries to your APK. You can verify this by going into your build settings and ensuring that the Android Private Libraries are checked. This will ensure that whatever is stored in your projects libs folder will be properly exported in your APK.
If this is not checked, the Google Play Services library doesn’t get included in your APK and you won’t be able to run your app.
Adding the necessary permissions
In order to run Google Maps in your android application, you need to add a set of permissions to your applications manifest.
You need to make sure that the following properties are added. (put them before the starting application tag) :
Setting up the map key
Inside the application tag we need to specify our map key. This needs to be done by adding a meta-data element inside the application element:
The whole proceess of getting a key is described in great length on the Google Android Maps v2 page so I’m not going to discuss it here. I do highly recommend that you read it to obtain your API key.
I’ve tried to summarize the process in the picture below, showing you the relationships between
The SHA1 fingerprint of your keystore
Your application pacakge name
The API console
Adding the map fragment
Assuming you’ve added the permissions and the API key to your application manifest, we can now start by putting a full-screen map into our application. For the moment we won’t be worrying about ActionBarSherlock just yet.
In order to add the map to our application we need to do 2 things.
Define and add the fragment to the layout
Implement the fragment
Adding the fragment to a layout is very simple.
The Google Play Services library provides a simple MapFragment (com.google.android.gms.maps.MapFragment) that can be used out of the box. Note that the MapFragment requires the native API Level 11 fragment implementation, so it’s only available on devices with API level 11 and higher. Attempting to run the example below on devices with a lower API level will fail with the following error
We’ll talk about how to run this example on lower API levels in a minute.
For now, we’ll stick with API level 11 and higher by adding the MapFragmnet to the layout like this :
Create the activity that will load up the layout above:
Note that in order to interact with the map, you need to get a reference to the GoogleMap object. The GoogleMap object can be retrieved via the MapFragment. In order to get a reference to the MapFragment in an Activity you need to retrieve the FragmentManager using the getFragmentManager call. This call is only available on API level 11 and up so you need to have your minSDK set to 11 if you want to run this.
googleMap.setMyLocationEnabled(true);
Running on lower API levels
Google also provides a SupportMapFramgment (com.google.android.gms.maps.SupportMapFragment) in Google Play services to be used with the Android Support package’s backport of fragments. In other words, the SupportMapFragment can be used on Android devices running API 10 and lower, as well as Android devices running 11 and higher.
In order to use the new Google Maps V2 API on older devices we need to do 3 things
use a SupportMapFragment instead of a MapFragment in your layout
use a FragmentActivity instead of an Activity
use the SupportFragmentManager instead of the FragmentManager in your FragmentActivity
Our layout will now look like this :
And our FragmentActivity will look like this :
Important note : Keep in mind that although the MapFragment can run in an Activity, the SupportMapFragment cannot, and needs to run in a FragmentActivity.
Simply let your activity extend from FragmentActivity instead of Activity to resolve this.
If you attempt to run a SupportMapFragment inside an activity, you’ll get the following error:
Adding the ActionBarSherlock.
The point of this article was to show you how you can include the ActionBarSherlock in your app, so lets get started with that.
With ABS 4.3 it couldn’t be simpler. Simply have your activity extend SherlockFragmentActivity like this
If you want to include a menu simply add this
If you want to split the actionbar you’ll need to add the following option to your activity in the applications manifest.
Older Android version
You’ll also notice that despite using the Android Support Library and Action Bar Sherlock that the app doesn’t run on older API versions. The application crashes with the following error :
Notice the following in the manifest
This can be easily fixed by using the Theme.Sherlock in our application.
android:theme="@style/Theme.Sherlock">
Or even better by specifying your application style in the styles.xml file
And using it in your application manifest like this: