Creating a Google Maps Android Project

The purpose of this post is to document the steps one must go through in order to create a functioning starting point for a Google Maps Android Project. There are a few points that are not well documented and/or oddities during the process. Hopefully this will help the developer overcome these issue when generating an Android project that requires Google Maps. At the end of this post the developer should have a fully compiled, error free Android Project with a MapActivity as the main class. In general this covers

  • Creating and configuring an Eclipse Android project for a MapActivity
  • Obtaining an API Key from Google for debugging purposes

To get started launch the New Project Dialog Box in Eclipse. Choose “Android Application Project” this will launch a wizard that will create a basic Android Application.

Create a New Android Project

Input the basic details in the wizard. I named my application “MapProject” this created a project with the same name and a package named “com.example.mapproject”. Feel free to personalize these details. The Build SDK must utilize a Google API package, on my machine my most recent version is Google APIs (Google Inc.) (API 16) so I am using that. For the purpose of this post the minimum SDK is not of great importance so set it to something reasonable. I am setting mine to API 9 Android 2.3. In the Second screen I choose “Blank Activity”. On the final screen I kept all of the defaults. Note: I attempted to set the “Hierachical Parent” to MapActivity in the hopes that the Wizard would setup the initial project in the form of a MapActivity but on my machine it did not, it still created the simple “Hello World” project. Feel free to try setting this to MapActivity maybe it will work better for you.

In order to get a proper MapActivity working for the project a few changes to some of the files will be required. Let’s start with the foundation of all Android apps the AndroidManifest.xml file. The manifest should look like something like this.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.mapproject"
    android:versionCode="1"
    android:versionName="1.0" >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-sdk
        android:minSdkVersion="9"
        android:targetSdkVersion="15" />
    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <uses-library android:name="com.google.android.maps" />
        <activity
            android:name=".MapScreen"
            android:label="@string/title_activity_map_screen" >
            <meta-data
                android:name="android.support.PARENT_ACTIVITY"
                android:value="com.google.android.maps.MapActivity" />
             <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Customize the package name and other details specific to your project (i.e choices such as activity name and label). There are some important settings here that the initial setup wizard did not create. Inside of the manifest node add the permission for the app to utilize the internet and location services.

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

Location services is not pertinent to the execution of this project but most likely one would want some location based functionality when utilizing the MapActivity, if not feel free to remove these permissions. Inside of the application node add the reference to the Google Maps Library

 
    <application
        android:icon="@drawable/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
        <uses-library android:name="com.google.android.maps" />
.... more stuff here

The next thing to change is the Layout of the main activity it will be located under the “res/layout” directory of the Android project. If you have been following these instructions it will be the only file in this directory. Currently it probably has a RelativeLayout tag and a TextView with a Text value reading “Hello World” change that to the XML below. Paste over this with the following and save the project.

<?xml version="1.0" encoding="utf-8"?>
<com.google.android.maps.MapView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_height="fill_parent" android:apiKey="@string/debugGoogleMapsKey" 
    android:layout_width="fill_parent" android:id="@+id/mapview" 
    android:clickable="true" />

There should be an error reported at this point refering to not being able to find the android:apiKey. the xml attribute is refering to a missing property that should be defined in “res/values/string.xml”. Access that file and define the String value

<string name="debugGoogleMapsKey">0-z-JPmZkrxLZR7v7q8Znd-58OsW1pfvmcmYjcg</string>

This bring us to the next somewhat complicated matter for setting up a Gogle Maps project on Android. An API Key from Google is required in order to utilize a MapActivity, even for Debugging purposes an API Key is required. To get a Key from Google provide them an MD5 Signature Google in turn will give provide an API Key. The API key received from Google should be placed in the “debugGoogleMapsKey” String value in “res/values/string.xml”. Note, Declaring this “debugGoogleMapsKey” value as a String is not required one could place the API Key  directly into the “android:apiKey“ value of the layout file. The API Key retrieved from Google will be for the DEBUG mode of your application. When releasing an application into the Google Play Market retrieve another API Key, this new key will be the production release API key. This is an important point to remember when you launch an application to the public.

As mentioned earlier to get the API Key one must provide Google an MD5 Signature. To generate the MD5 signature utilize the Java “keytool” utility. Follow these steps to generate the signature.

  1. Open a Terminal Window
  2. Navigate to the location where android debug keystore is located. On a Mac the default location is “/Users/[username]/.android” check https://developers.google.com/maps/documentation/android/mapkey for the location associated with your operating system.
  3. Run the following command
    keytool -list -keystore debug.keystore -storepass android

    Note the default password is android the result should look something like this.

    androiddebugkey, Feb 11, 2012, PrivateKeyEntry, 
    Certificate fingerprint (MD5): 8C:12:08:B1:42:40:78:0B:3A:76:55:C6:55:94:31:71

Copy the generated MD5 signature to your clipboard (Just the MD5)

8C:12:08:B1:42:40:78:0B:3A:76:55:C6:55:94:31:71

After you have the signature access the URL https://developers.google.com/android/maps-api-signup to input the MD5 Signature and retrieve your API Key. The result should look something like this.

Input the value displayed in the “key” section into the debugGoogleMapsKey String property mentioned earlier.

The final piece to setting up a Google Maps Android development project is to refactor the Activity Class associated with the MapActivity. Here is a copy of the refactored source from my project.

package com.example.mapproject;

import com.google.android.maps.MapActivity;
import android.os.Bundle;

public class MapScreen extends MapActivity {

    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_map_screen);
    }

    @Override
    protected boolean isRouteDisplayed() {
      // TODO Auto-generated method stub
      return false;
    }
}

Change the extended class from Activity to MapActivity this will require the method “isRouteDisplayed” to be implemented. As long as there are no outstanding errors the application should be ready to be ran in a VM or on a device. In Eclipse, Right clicking the application, Choosing “Run As” and “Android Application” Should launch the Application in an Android VM,  you should get a screen similair to this.

It doesnt really do anything but this is in a state ready for development.

If there are runtime problems most likely there is some naming issues that needs to be fixed. Check the manifest file to ensure the activity name is correct, ensure XML properties in AndroidManifest and the layout are refering to there proper places.

Here are some good references for getting your Google Maps Android project up and running.

http://www.javacodegeeks.com/2011/02/android-google-maps-tutorial.html

https://developers.google.com/maps/documentation/android/mapkey

 

Source code for this project is available at https://davet-personal-repo.googlecode.com/svn/MapProject

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>