Migrating an App from Google Maps

Introduction

The Amazon Maps API provides mapping functionality for Android apps on most Kindle Fire tablets. If your app uses Google Maps, which is not available on Amazon devices, you can migrate your app to the Amazon Maps API. The Maps API offers interface parity with the Google Maps API v1.

Before migrating your app, you must first set up your development environment for the Maps API. See Building and Testing Your Maps App for more information.

Be aware of the following differences between the Amazon Maps API and Google Maps:

  • Traffic. The map does not display traffic information. The MapView.setTraffic() method accepts a Boolean value and the MapView.isTraffic() method returns the Boolean value, but the value has no effect.

  • Street view. The map does not display street view availability. The MapView.setStreetView() method accepts a Boolean value and the MapView.isStreetView() method returns the Boolean value, but the value has no effect.

  • Trackball gestures. While the Amazon Maps API provides the TrackballGestureDetector class to ensure interface parity, it does not support trackball events.


Migrating Your App to the Amazon Maps API

To migrate your app to the Amazon Maps API, do the following:

  1. Create a new Android project and configure your project to build against the Amazon Maps API.

    For information about how to configure your project, see Building and Testing Your Maps App.

  2. Migrate your code from the existing project for your app to the new project:

    • From the existing project, import your libraries, resources, and source files.

    • In your Java class files and resources, convert all references from com.google.android.maps to com.amazon.geo.maps. The Amazon Maps API uses the package name com.amazon.geo.maps.

    Optionally, you can remove android:apiKey attributes from MapView objects. The Amazon Maps API identifies your app by developer signature and package name, and does not look for a maps API key. Your migrated app can continue to pass a maps API key, but it has no effect for the Amazon Maps API.

  3. In the AndroidManifest.xml for your app, do the following:

    • In the manifest element, add the attribute xmlns:amazon="http://schemas.amazon.com/apk/res/android".

    • In the application element, add the child element <amazon:enable-feature android:name="com.amazon.geo.maps" android:required="false" />. The setting android:required="false" assumes that your application gracefully degrades when the maps library runtime is unavailable.

    • In the application element, because Google Maps is not available on Amazon devices, replace <uses-library android:name="com.google.android.maps" /> with <uses-library android:name="com.google.android.maps" android:required="false" />.

    For example:

                                                    <?xml version= "1.0" encoding= "utf-8" ?>
                                                    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
                                                      xmlns:amazon="http://schemas.amazon.com/apk/res/android"
                                                      package ="com.example.android.myapp"
                                                      android:versionCode="2"
                                                      android:versionName="2.0" >
                                                     
                                                      <application>
                                                       											
                                                        <!-- Enable Amazon Maps on Amazon devices. -->
                                                        <amazon:enable-feature android:name="com.amazon.geo.maps" android:required="false" />
                        							 
    												    <!-- Make Google Maps library optional. -->
    												    <uses-library android:name="com.google.android.maps" android:required="false" />
                                                     
                                                      <!-- Lines removed for clarity. -->
                                                     
                                                      </application>
                                                     
                                                    </manifest>
                                                
  4. Verify the following Android permissions in the AndroidManifest.xml for your app:

                                                    <?xml version= "1.0" encoding= "utf-8" ?>
                                                      <manifest xmlns:android="http://schemas.android.com/apk/res/android"
                                                       
                                                      <!-- Lines removed for clarity. -->
    												                                                   
                                                      <uses-permission android:name= "android.permission.INTERNET" />
                                                      <uses-permission android:name= "android.permission.ACCESS_COARSE_LOCATION" />
                                                      <uses-permission android:name= "android.permission.ACCESS_FINE_LOCATION" />
                                                    
                                                      <!-- Lines removed for clarity. -->
                                                     
                                                    </manifest>
                                                

    Your app must request android.permission.INTERNET to download map tiles. An app that uses locations or uses the MyLocationOverlay class must also request android.permission.ACCESS_COARSE_LOCATION and android.permission.ACCESS_FINE_LOCATION.


Modifying Your App to Gracefully Degrade

Make sure to design your app so that the app gracefully degrades when the Amazon Maps API is unavailable. You can then build a single APK to be installed and run on multiple Amazon devices, including the Kindle Fire (1st Generation) device, which does not have the maps library runtime.

To modify your app to gracefully degrade, do the following:

  1. In your app, use code similar to the following to check for the maps library runtime.
                                                    mAmazonMapsAvailable = false ;
                                                    try {
                                                         Class.forName( "com.amazon.geo.maps.MapView" );
                                                         mAmazonMapsAvailable = true ;
                                                    }
                                                    catch (Exception e) {}  
                                                
  2. Add the following code to any of your code that requires the maps library runtime.

                                                    if (mAmazonMapsAvailable) {
                                                        // Your code that requires maps
                                                    }
                                                
  3. In your AndroidManifest.xml file, verify that the application element specifies <amazon:enable-feature android:name="com.amazon.geo.maps" android:required="false" />.


Next Steps

You can now build and test your migrated app. For more information, see Building and Testing Your Maps App.


Return to the Amazon Maps API

Unavailable During Maintenance