How to configure Google Maps Android API v2 in Titanium Studio

We all know that a big part of mobile apps requires a map. Configuration process is quite simple, but sometimes we need to remember or find a list of required permissions for android or just strugle with new OS or new SDK and this routine takes more time that we want. This time I decided to combine all needed steps in one place and write a short guide how to set up android google maps api v2 in Titanium Studio. Hope this will help you as it helps me know. 

Generation of Google maps API Key

To work with Google maps you need to have an API key (even for development purposes). I use Titanium Studio for development and that's why I need to figure out where it stores android keystore file which it uses to sign applications under development build (dev_keystore in our case). We can easily figure this out by listing all installed Titanium SDK versions:

ti sdk list

This will show as not only all versions, but the important for us part too - paths where they’re installed:

Titanium Command-Line Interface, CLI version 3.4.1, Titanium SDK version 3.4.1.GA

#...

SDK Install Locations:

   /Library/Application Support/Titanium

   /Users/melnik/Library/Application Support/Titanium [default]

Installed SDKs:

   3.4.1.GA [selected]  /Users/melnik/Library/Application Support/Titanium/mobilesdk/osx/3.4.1.GA

   3.4.0.GA             /Users/melnik/Library/Application Support/Titanium/mobilesdk/osx/3.4.0.GA

   3.3.0.GA             /Users/melnik/Library/Application Support/Titanium/mobilesdk/osx/3.3.0.GA

Now, as we want to find dev_keystore file for android, we just need to find android folder inside SDK, that’s it. The final path in my case is:
 

~/Library/Application\ Support/Titanium/mobilesdk/osx/3.4.1.GA/android/dev_keystore

Now we need to get SHA1 from the dev_keystore file:

keytool -v -list -keystore <path to your dev_keystore file>

By default dev_keystore file isn’t protected via a password, so just hit Enter when keytool asks you to provide it. Then you will see SHA1 in the output, like:

Certificate fingerprints:
    
#...
# here is the most important part for us:

     SHA1: XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX

     Signature algorithm name: MD5withRSA

     Version: 1

Just copy it somewhere, we will use it later in Google developers console. Also we need to copy Application Id, you can find it in tiapp.xml:

titanium application id

Creation of a new project in Google Play developers console

We need to log in developers console and create a separate project for our future Titanium project.

Enable maps in console

For example I created Map demo project and just need to open it and then go to APIs & auth -> APIs section. There I need to find Google Maps Android API v2 and enable it. 

Creation of a new API key

Now we can create a new android api key. We need to go to APIs & auth -> Credentials and create a new key for public API access (select Android key in popup). There you need to put your SHA1 and application id in the next format:

# SHA1;AppId
XX:XX:XX....;com.example.demo

Now you can see your API key. Please copy it, we will use it in our Titanium application to get access to maps.

Configure the project in Titanium Studio

Now we have all required keys from Google Maps and we can configure our Titanium project to add maps support to it.

Add ti.map module via tiapp.xml

First of all we need to include module ti.map in our application. You can do it in tiapp.xml editor under "Modules" section. Just hit "+", find there ti.map and that’s it.

Configure credentials

If we want to use maps (and we really want :) ), then we need to add all required by a map credentials to our tiapp.xml. Here is the template:

<android xmlns:android="http://schemas.android.com/apk/res/android">
        <manifest>
            <!-- Allows to use MOCK GPS data from emulators -->
            <uses-permission android:name="android.permission.ACCESS_MOCK_LOCATION"/>
            <!-- Allows the API to download data from Google Map servers -->
            <uses-permission android:name="android.permission.INTERNET"/>
            <!-- Allows the API to cache data -->
            <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
            <!-- Use GPS for device location -->
            <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
            <!-- Use Wi-Fi or mobile connection for device location -->
            <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
            <!-- Allows the API to access Google web-based services -->
            <uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>
            <!-- Specify OpenGL ES 2.0 as a requirement -->
            <uses-feature android:glEsVersion="0x00020000" android:required="true"/>
            <!-- TODO: double check your app ID here -->
            <uses-permission android:name="<YOUR APP ID>.permission.MAPS_RECEIVE"/>
            <!-- TODO: double check your app ID here -->
            <permission 
                android:name="<YOUR APP ID>.permission.MAPS_RECEIVE" android:protectionLevel="signature"/>
            <application>
                <!-- Google API key -->
                <!-- TODO: double check your API key here -->
                <meta-data 
                    android:name="com.google.android.maps.v2.API_KEY" android:value="<YOUR MAPS V2 API KEY>"/>
            </application>
        </manifest>
    </android>

Just add it to your tiapp.xml under android section/tag. Here we have 3 plases that should be updated with your real values:

YOUR APP ID - (example: com.example.mapdemo)

YOUR MAPS V2 API KEY - put here the key you’ve got in google developers console in previous steps.

That's it. Now your Titanium application is properly configured and able to work with Google Maps API v2.

Test code sample

With code sample below you can test if map is configured properly and works in your new application.

// app/controllers/index.js
var Map = require('ti.map'),
    mapView = Map.createView();
 
$.index.add(mapView);
$.index.open();
<!-- app/views/index.xml -->
<Alloy>
    <Window class="container">
    </Window>
</Alloy>

Just run it on android emulator or a device. Also don't forget to read about titanium map module in docs

Conclusion

It’s quite easy to configure your Titanium application to support Google Maps Android API v2 and I hope this little guide helped you and saved some time.