HowTo: Using Maps with Android

Overview

Google requires a different Map API key for each certificate that signs an Android application. What this means for you, is one API key when developing your application and one when you build the production version. API Keys can be obtained without a fee from Google. For more a more in depth overview, read the Google Maps External Library overview.

> Note: We hope to provide additional tooling in the future to help with API Key generation and management.

There are just a few steps required and while it may look complicated, it's very straight-forward. You should create a document/spreadsheet where you maintain a list of applications and their certificate hash (MD5) with the corresponding API key. If you decided not to, Google will return you the same API key for the same certificate hash.

Process Summary

Here are the basic steps.

  1. Obtain the MD5 hash of the certificate
  2. While you're logged in to Google(Gmail) paste the MD5 of the certificate into the appropriate form, agree to the license, and submit.
  3. Copy the Map API key that Google creates and save it. (if it's lost simply repeat the process with the same MD5)
  4. Put it in tiapp.xml in the property ti.android.google.map.api.key
  5. Verify your Android Virtual Device uses the Google APIs system image.
    <property name="ti.android.google.map.api.key">Your Key Here</property>

Obtaining the MD5

Google uses the MD5 fingerprint of the certificate that signs your mobile application to generate a Maps API Key. This API Key is needed by Titanium when constructing the MapView. When your mobile application is run on the emulator or on a device, the underlying Maps implementation verifies that the API key used to pull map data matches the certificate which signed your application.

To obtain the MD5 you need: 1. The path to the keystore 2. The keystore password 3. The key alias (name)

Most likely you generated your production key after referencing HowTo: Package for the Android Market. So the information is only known by you and you just need to fill in the blanks.

However, every Titanium Developer installation has a debug key that ships with the mobilesdk so we can use that for our example.

The Path to the Keystore

This path varies per OS and in the case of Windows, per OS Version. The general pattern is as follows:

<pre> <b>OS SPECIFIC ROOT</b>/Titanium/mobilesdk/<b>OS CODE</b>/<b>SDK VERSION</b>/android/dev_keystore </pre>

OS X

  • OS SPECIFIC ROOT: /Library/Application Support/Titanium
  • OS CODE: osx

Linux

  • OS SPECIFIC ROOT: ~/.titanium or /opt/titanium
  • OS CODE: linux

Windows - XP

>Note: You can always search your drive using dir /s/b titanium from the root of your C drive.

  • OS SPECIFIC ROOT: C:Documents and SettingsAll UsersApplication DataTitanium
  • OS CODE: win32

Windows - Vista

  • OS SPECIFIC ROOT: C:UsersYOURACCOUNTAppDataRoamingTitanium
  • OS CODE: win32

Windows - 7

  • OS SPECIFIC ROOT: C:ProgramDataTitanium
  • OS CODE: win32

SDK VERSION is usually a string like 0.8.0.

The Keystore Password

The password for the development key is tirocks

The Key Alias

The alias for the development key is tidev;

Obtaining the Key

<pre> keytool -list -keystore PATH_TO/dev_keystore -alias tidev -storepass tirocks </pre>

Keytool will output a few lines. The important one is:

<pre> Certificate fingerprint (MD5): <b>66:5E:D1:7F:C4:2C:B9:73:AD:7F:4D:DD:29:12:56:56</b> </pre>

Certificate Example

Google's form wants the information shown in bold, (i.e. just the fingerprint).

Obtaining a Key From Google

Once you have the MD5 fingerprint, log in with your Google(Gmail) account and visit the Maps API Key Signup form.

Signup form

Paste in your fingerprint and agree to the terms then press Generate API Key. You should see a result similar to the image below.

API Key

Modify tiapp.xml

The final step in this process involves adding a single element to your tiapp.xml. Using your favorite text editor go to your project folder and open your tiapp.xml. Navigate to the bottom of the page and insert the following fragment after the &lt;/windows&gt; tag and before the &lt;/ti:app&gt; tag.

Editing tiapp.xml

Verify your AVD Target

Google Maps are an add-on and are not part of the open source platform. Most Android devices have shipped with some proprietary Google applications like Maps. However, there are no requirements that a device manufacturer ship a Google Phone. If you do want to run on a non-Google device or emulator system image, you will need to have a different version of your app that doesn't require maps.

>Note: The current, 0.8.0, Android mobilesdk ships with embedded Map support. You will need a Google capable device and AVD until we complete the modularization of the SDK.

>Note: If you're still on the old Android SDK 1.5 or 1.6 instead of the SDK Kit, you should move up to the new tooling. Future documentation will feature the tools. Specifically the android GUI.

Open a command window or terminal and run the following command

android list avd
The result is a list of all of your AVDs. Titanium Developer uses the AVD named titanium. Look for it in the list.
Odin01:android dthorp$ android list avd
Available Android Virtual Devices:
    Name: Test1
    Path: /Users/dthorp/.android/avd/Test1.avd
  Target: Android 1.6 (API level 4)
    Skin: HVGA
  Sdcard: /Users/dthorp/.titanium/android.sdcard
---------
    Name: titanium
    Path: /Users/dthorp/.android/avd/titanium.avd
  Target: Google APIs (Google Inc.)
          Based on Android 1.5 (API level 3)
    Skin: HVGA
  Sdcard: /Users/dthorp/.titanium/android.sdcard
Notice there are two devices list. One uses the non-Google aware Android 1.6 (API level 4) target and the other one, titanium, uses the Google APIs (Google Inc.) Based on Android 1.5 (API level 3).

If your titanium AVD doesn't use a Google image, you'll need to covert it. The easiest method is to delete the image and let Titanium Developer re-create it.

To delete the image run the following command.

android delete avd -n titanium

Tips

  • Create a document or spreadsheet where you maintain a list of applications, their certificate hash (MD5) with the corresponding API key. If you decided not to, Google will return you the same API key for the same certificate hash.

  • The MD5 fingerprint of the debug key is the same, you can just copy the following MD5 fingerprint and use it on the form. The resulting API Key can be used during development for all of your projects.

<pre> Certificate fingerprint (MD5): <b>66:5E:D1:7F:C4:2C:B9:73:AD:7F:4D:DD:29:12:56:56</b> </pre>