Migrating an App from Google Maps v2

Introduction

The Amazon Maps API provides mapping functionality for Android apps on Fire tablets and Fire phone. If your app uses Google Maps, you can migrate your app to the Amazon Maps API by making some minor code changes and then re-compiling your app against the Amazon Maps API. You can then run your app on Fire phone and Fire tablet devices and distribute your app in the Amazon Appstore for Android.

The Amazon Maps API offers interface parity with version 2 of the Google Maps API. Most classes and method calls in your Google Maps app work the same on Amazon devices. For information about the differences, see Differences between Amazon Maps and Google Maps.

Steps to Migrate Your App

To migrate your app:

  1. Configure your project with the Amazon Maps API Library. See Configuring Your Project to Use the Amazon Maps API. These steps include:
    • Making sure your app permissions in the AndroidManifest.xml are correct.
    • Updating the Fire OS API level in your AndroidManifest.xml.
    • Importing the Amazon Maps API Support Library and configuring your project to compile against it.
  2. Rename Google–specific namespaces and classes to the Amazon–named versions as described below.
  3. Rename Google–specific XML attributes in your resource files as described below.
  4. Remove the project's existing dependency on the Google Play services library. This ensures that the compiler flags any code that still references Google Play services classes.
  5. Register your app to download map tiles. See Registering and Testing Your App.
  6. Test your app on an Amazon device. Pay special attention to any areas where you used features that are not supported in the Amazon Maps API. For a list of these areas, see Differences between Amazon Maps and Google Maps.

Renaming Namespaces and Classes

The following table lists the Google–specific namespaces and classes that you must rename to the Amazon versions. You may find it useful to use find and replace tools in your IDE to make these updates.

Google Name Amazon Name
com.google.android.gms.maps com.amazon.geo.mapsv2
com.google.android.gms.common.GooglePlayServicesUtil com.amazon.geo.mapsv2.util.AmazonMapsRuntimeUtil
GoogleMap AmazonMap
GoogleMapOptions AmazonMapOptions
GooglePlayServicesUtil.isGoogleSignedUid AmazonMapsRuntimeUtil.isAmazonSignedUid

Renaming XML Attributes

A Google Maps–compatible app can use custom XML attributes in a layout XML file to set initial map options. For example, you can specify map:mapType="satellite" to set the initial map type to satellite.

The Amazon Maps API supports the same set of XML attributes, but they are named with an amzn_ prefix. If you are using the XML attributes in your app, you need to rename them with the Amazon versions.

Google XML Attribute Amazon XML Attribute
mapType
Possible values for this attribute:
  • none
  • normal
  • hybrid
  • satellite
  • terrain
amzn_mapType
Possible values for this attribute:
  • amzn_none
  • amzn_normal
  • amzn_satellite
  • amzn_terrain
  • amzn_hybrid
cameraTargetLat amzn_cameraTargetLat
cameraTargetLng amzn_cameraTargetLng
cameraZoom amzn_cameraZoom
cameraBearing amzn_cameraBearing
cameraTilt amzn_cameraTilt
uiZoomControls amzn_uiZoomControls
uiCompass amzn_uiCompass
uiZoomGestures amzn_uiZoomGestures
uiScrollGestures amzn_uiScrollGestures
uiRotateGestures amzn_uiRotateGestures
uiTiltGestures amzn_uiTiltGestures
zOrderOnTop amzn_zOrderOnTop
useViewLifecycle amzn_useViewLifecycle

For details about using XML attributes for map settings, see Displaying an Interactive Map with the Amazon Maps API v2. The available XML attributes are also documented with their related AmazonMapOptions methods in the Maps API Reference.

Testing Your Migrated App

When testing your migrated app on an Amazon device, pay special attention to any areas where you used features that are not supported in the Amazon Maps API. You can turn on strict mode to help find these areas. Strict mode causes the methods used for these features to log warnings or throw exceptions instead of silently failing.

For details about the unsupported features and using strict mode, see Differences between the Amazon Maps API 2 and Google Maps API v2

For details about registering your app, see Registering and Testing Your Amazon Maps API v2 App.

For additional help and information, see the Amazon Maps API Frequently Asked Questions.