Getting Ready to Use Google Maps Android API v2

Why do we need another tutorial for Google Maps Android API v2? I have discovered little things are missed or inaccurate in tutorials here and there (even in Google’s developer guideline). I do not want to repeat every single detail that you can find other places. This can be a supplementary material for Google’s developer guide for Google Maps Android API v2.

We know what the Google Maps is already. Also the 2nd version was introduced many months ago. Google Maps API in Android was also improved and named v2. Many things have  changed since last year.

Let’s get started. I am assuming we are using Eclipse as an IDE.

Install Google Play services SDK

To use Google Maps in Android we should have Google Play services. I don’t know why Google uses the name “Play” for Maps services. Anyway…

  • Start the Android SDK Manager.
  • Find Google Play services in the Extras.
  • Install the package by clicking “Install …” button.

Get the library for Google Play services

After the package is installed. We have to make the library usable for other projects.

  • Import the library so that my project can use it.
    • Go to File > Import > Android > Existing Android Code … and click Next.
    • Browse and find “<your android sdk folder>/extras/google/google_play_services/libproject/google-play-services_lib” and click Finish.
  • We just installed Google Play services library.

Make the sample app, maps work.

There are few samples in the Google Play services SDK. Let us make “maps” work. We could use this as a working template that can be utilized for future projects.

  • Import the sample.
    • Go to File > Import > Android > Existing Android Code … and click Next.
    • Browse and find “<your android sdk folder>/extras/google/google_play_services/samples/maps”.
    • The default new project name of the sample is “MainActivity.” This is not a smart choice at all. Let us change it to something more meaningful such as “MapsSample” before you click the Finish button.
    • Also make sure that you check “Copy projects into workspace” so that the original code is intact.
  • Well.. you can see tons of errors. Look hopeless. But do not worry. We will fix them shortly.
    • Go to Project > Properties.
    • Find Android in the left. You will see the Library pane in your right. If you see the ‘X’ mark in red, select it and click Remove.
    • Click Add… and select the “google-play-services_lib” item. Click OK. Now you can see the check mark in green.
  • Most errors should be gone now. RetainMapActivity has some errors that are from using “FragmentActivity.”
    • Fragment was introduced in Android 3.0 (API level 11). ADT (Build: v21.1.0-569685) makes templates using minSDK 8. The example was written using Support Lib anyway. Let us use the support library.
  • Add a support lib v4 into the project.
    • Make the “libs” folder inside the project folder. If you followed my recommendation in naming the project, the folder name is “MapsSample” and the “libs” folder must be inside the folder.
    • Find “android-support-v4.jar” at “<your android sdk folder>/extras/android/support/v4/” and copy it into the “libs” folder.
    • Go to Project > Properties.
    • Find “Java Build Path” in the left. Select the “Libraries” tab and click “Add External JARs…” Find the “android-support-v4.jar” file. Note: Do not select the jar file inside the Android SDK folder.
    • This must remove all remaining errors.
  • Run the app. You may see the program crashes.
    • Go to Project > Properties.
    • Find “Java Build Path” in the left. Select the “Libraries” tab.  Find the “android-support-v4.jar” file and remove it. I know, I know.. This is a strange step. But it should fix the crash.
  • If you still see errors from GoogleMap related packages and classes, just choose “Fix project setup..” from the Quick Fix suggestion and select “Add archive ‘google-play-services.jar – ….” and click OK. This will add “google-play-services.jar” into the build path.

Emulator

As of writing this Android emulator does not support Google Play services. We should use an actual Android device.

API Key

An API Key is required to use Google Play services.  To get a key we need an SHA-1 fingerprint and the application registration with the Google Maps Android API v2.

SHA-1 fingerprint

  • Locate debug.keysotre file in the “.android” in the current user folder.
    • /Users/&lt;user name&gt;/.android/ or ~/.android/
  • List the SJA-1 fingerprint.
    • keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
  • Find the “SHA1:” line in the output.
    • Alias name: androiddebugkeyCreation date: Apr 4, 2013
      Entry type: PrivateKeyEntry
      Certificate chain length: 1
      Certificate[1]:
      Owner: CN=Android Debug, O=Android, C=US
      Issuer: CN=Android Debug, O=Android, C=US
      Serial number: 515de791
      Valid from: Thu Apr 04 16:50:25 EDT 2013 until: Sat Mar 28 16:50:25 EDT 2043
      Certificate fingerprints:
      MD5: 11:22:33:44:A8:0E:99:00:33:94:44:33:55:7E:66:FD
      SHA1: <span style="color:#ff0000">FF:CC:BB:16:99:E3:AA:FF:55:44:42:77:AE:55:46:99:43:55:88:C2</span>
      Signature algorithm name: SHA1withRSA
      Version: 3
    • Copy the hexa-decimal string after “SHA1:” (Note that the string above is not actual fingerprint)

Registration

  • Go to https://code.google.com/apis/console/
  • Select “Services” and find “Google Maps Android API v2” in the middle of the list.
    • Turn the switch on.
  • Select API Access.
    • Click “Create new Android key…”
    • Paste the copied SHA-1 fingerprint and put ‘;’ followed by the package name (com.example.mapdemo).
  • Find “API key:” in the “Key for Android apps (with certificates)”

Put the Key into AndroidManifest.xml

Locate AndroidManifest.xml and open it. Find “YOUR_OWN_KEY” and replace it with the API key.

[code language=”xml”]
<application
android:icon="@drawable/ic_launcher"
android:label="@string/demo_title"
android:hardwareAccelerated="true">
<meta-data
android:name="com.google.android.maps.v2.API_KEY"
android:value="YOUR_OWN_KEY"/>
[/code]

Connect your Android device and execute the sample. You will see “Google Maps API Demos” app.