Getting a Signing Certificate While Debugging

When you’re creating and debugging your application that uses a MapView, or when
you’re running a demo application like MJAndroid, you still need a valid Map API Key
to get map tiles from Google Maps, and you need the fingerprint of your debug signing
certificate to obtain a Map API Key. You can’t just use the apiKey that we have coded
into the MJAndroid source files, because it is tied to the signing certificate that was
generated by our debug environment. Your debug environment will generate its own,
different signing certificate for you to use, so you need to obtain a Map API Key to
match.
There are two steps to getting the key:
1. Get a copy of the MD5 fingerprint for your Debug signing certificate.
2. Use that fingerprint to obtain a valid Map API Key from Google and enter it into
AndroidManifest.xml.


Getting the MD5 fingerprint of your Debug signing certificate
When the Android SDK automatically generates a Debug signing certificate for you, it
places it in a keystore called debug.keystore. The trick is to find this keystore. At least
for the current version of the SDK, as this is being written, the location is operating
system dependent:
• Under Linux and Mac OS X, it is in the .android subdirectory under your home
directory: ~/.android/debug.keystore.
• Under Windows Vista, it’s a little harder to find; it’s under your personal
Application Data directory: C:\Users\your_username\AppData\Local\Android
\debug.keystore.
• Windows XP is similar to Vista: C:\Documents and Settings\your_username\Local
Settings\Application Data\Android\debug.keystore (unlike Vista, you will need to
use a quoted string for the XP shell).
Once you’ve found debug.keystore, keytool can give you the MD5 fingerprint of your
Debug signing certificate. Under Linux or OS X you’d type:
$ keytool -list -alias androiddebugkey -keystore ~/.android/debug.keystore -storepass
android -keypass android
For Vista or XP, just substitute the correct location in the -keystore option. keytool
prints the date the Debug signing certificate was created and the MD5 fingerprint. As
an interesting note, Debug signing certificates are good for 365 days after creation.

What Happens When My Debug Signing Certificate Expires?
After your certificate expires, you’ll get a build error whenever you try to build your
application. The error will be displayed on the Android console (one of the tabs in the
bottom pane of the Java and DDMS Perspectives), and it will say something like:
debug:
[echo] Packaging bin/samples-debug.apk, and signing it with a debug key...
[exec] Debug Certificate expired on 8/4/08 3:43 PM
To fix it, just delete your debug.keystore file (see the earlier list for its location in different
host operating systems). The next time you build, the Android SDK will generate a new
debug.keystore with a new Debug signing certificate, and your application can build
and run.

Now that you have the MD5 fingerprint of your Debug Signing Certificate, you can use
it to get a valid Map API Key for your system.
Getting a Map API Key from Google
Now that you have a signing certificate to use for your application, you can apply to
Google for a Map API Key. Map API Keys are tied to a signing certificate, so obviously
the Map API Key you get will work only with applications signed with the same certificate
(another good reason for sticking with the same certificate for all your applications).


Getting the key is pretty easy, and it’s free.
When an application that contains a MapView runs, it requests map “tiles” from Google
Maps via the Internet. As part of that request, it sends the Map API Key that was
obtained when the developer signed up with Google, as well as the MD5 fingerprint of
the application’s signing certificate. Google Maps checks to see that the key is registered
to a developer, and then checks to see that the Map API Key matches the one on file
for applications with that signing certificate fingerprint. If they match, it sends the
requested tiles. If they don’t match, no tiles are sent.
So we’re going to need the MD5 fingerprint of the signing certificate that we just created.
Fortunately, keytool can get that for us:
$ keytool -list -alias mjkey -keystore microjobs.keystore
keytool asks for the passwords to the keystore (and key, if they’re different), and prints
out the MD5 fingerprint in hexadecimal. Use your mouse to copy the fingerprint so
you can paste it into the Google page later.
Now you can go to the Google Map API Key website at http://code.google.com/android/
maps-api-signup.html to actually get the Map API Key. The Terms of Service are shown
in a text box. Read them, and if appropriate, click on the checkbox that indicates you
accept. Paste the MD5 fingerprint into the form, click the “Generate API key” button,
and the website will ask you to log into your Google account. If you don’t have a Google
account, you can quickly create one on the spot.
Once you log in, the website returns the Map API Key, which can be used with any
application that uses the signing certificate whose fingerprint you entered. It’s a long
alphanumeric string, so you will want to copy it into your clipboard and paste it into
the XML layout file for your Map Activity.
As an example, the XML layout file for MJAndroid’s Map Activity (called MicroJobs)
has the following section defining the MapView and the API Key that matches our
debug environment:
<com.google.android.maps.MapView
android:id="@+id/mapmain"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:clickable="true"
android:apiKey="0P18K0TAE0dO2GifdtbuScgEGLWe3p4CYUQngMg"
/>
Of course, you will have to substitute your own apiKey for ours.