Configuring Your Project to Use the Amazon Maps API v2

To use the Amazon Maps API, you configure your project to reference the Amazon Maps API Support Library. This is necessary both for coding directly against the API and for migrating an app from Google Maps.

Before you can configure your app, you need to set up your development environment.

See Getting Started with Android Studio for information about setting up the Android Studio development environment. We recommend that you use the Amazon Maps API with Android Studio.

Note: The Android SDK, Android Studio, and certain other development tools are provided by third parties, not by Amazon. Our links for these tools take you to third-party sites for downloading and installing the tools.

Updating the AndroidManifest.xml

Updating App Permissions

To use Amazon Maps API features, include the necessary permissions in your Android manifest. At a minimum, your app needs android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE for downloading map tiles.

If your app enables the user's location with AmazonMap.setMyLocationEnabled(), you also need android.permission.ACCESS_COARSE_LOCATION and android.permission.ACCESS_FINE_LOCATION. These additional permissions are only required if you are accessing the user's location.

Enabling Manifest Merging

The Amazon Maps API requires additional metadata tags in the AndroidManifest.xml file. You can set these automatically by enabling manifest merging. This automatically combines settings in library manifests with your project's manifest.

Manifest merging is enabled by default in Android Studio. For ANT, add this line in your project's project.properties file:

manifestmerger.enabled=true

Alternatively, you can manually add the following lines to the </code> element in your AndroidManifest.xml:

Referencing the Amazon Maps API Support Library

To use the Amazon Maps API in your project, download the SDK and add the Amazon Maps API Support Library to your project. The library is provided as a Gradle-compatible project. To get the SDK, do one of the following:

Configure the Android SDK Manager with the Amazon SDK Add-On (see Setting Up Your Development Environment. The Amazon Maps API v2 is available in the SDK Manager under Extras. Once installed, the libraries are in the <Android SDK Folder>\extras\amazon\mapsv2\lib\ folder:

Note: When using this method, you only need to configure the SDK Manager and then download the Maps API v2 from extras. You do not need to install the Fire Phone SDK, Fire Tablet SDK, or Fire Phone Build Tools to use the Maps v2 API.

Configuring Your Project in Android Studio

You can use the provided .AAR file with Android Studio. The library is in the \lib\aar folder.

We recommend that you install the Amazon Maps API Support Library in a local Maven repository, then reference it as a Gradle dependency.

Note: You should only need to complete the above steps once until a new version of the library is released. After the library is installed in a local Maven repository, you can add it as a dependency for any number of projects.

To configure the dependencies for your project:

Open or create your project in Android Studio.

In the project-levelbuild.gradle file, add mavenLocal() to the repositories section under allprojects. For example:

Note: An Android Studio project has multiple build.gradle files. The project-level build.gradle file is at the top level of the project structure and is normally used for project-level settings such as the repositories. For details about the different build.gradle files, see the "Project Build File" and "Module Build File" sections in Android Plug-in for Gradle.

In the module-levelbuild.gradle file for your app, remove the following line from the dependencies section if it exists:

compile project(':amazonmapsapiv2_lib')

Note: This line might not exist. It is added when importing projects from Eclipse.

Also in the module-levelbuild.gradle file for your app, add the following line to the dependencies section:

Verifying that Amazon Maps is Available on the Device

The Amazon Maps API is supported on the following devices running FireOS 4.5 or later:

Fire phone

Fire tablets (3rd Generation and later)

To ensure a good user experience, your app should check for the presence of the Amazon Maps API on the device and adjust accordingly if it is not available. A supported device may not have the necessary runtime if it has not yet received a system update.

To check for Amazon Maps, call AmazonMapsRuntimeUtil.isAmazonMapsRuntimeAvailable(). This method returns a result code as an int. Use the constants provided in the ConnectionResult object to determine the result. ConnectionResult.SUCCESS is returned if Amazon Maps is present.

Note: The AmazonMapsRuntimeUtil class is in the com.amazon.geo.mapsv2.util package.

For example, the following method returns a boolean indicating whether the Amazon Maps API is available:

importcom.amazon.geo.mapsv2.util.AmazonMapsRuntimeUtil;...privatebooleancheckForAmazonMaps(){// Check for the presence of Amazon Maps on the devicereturnAmazonMapsRuntimeUtil.isAmazonMapsRuntimeAvailable(this)==ConnectionResult.SUCCESS;}

The following example shows an onCreate method for an Activity that writes a message to the log if the Amazon Maps API is not available on the device:

@OverrideprotectedvoidonCreate(BundlesavedInstanceState){super.onCreate(savedInstanceState);setContentView(R.layout.activity_main);if(checkForAmazonMaps()){// Maps should be available. Code// to get a reference to the map and proceed// normally goes here...}else{// Maps is not available. Get the exact result// code and write it in a log messageintcr=AmazonMapsRuntimeUtil.isAmazonMapsRuntimeAvailable(this);Stringmsg=getString(R.string.no_maps)+" ConnectionResult = "+cr;Log.w(TAG,msg);}}

For an example of displaying an error dialog when the Amazon Maps API is not available on the device, see the CapitolHillCoffee sample app. The sample is available as part of the Apps & Games Services SDKs. For details about downloading, registering, and compiling the sample, see Using the Amazon Maps API v2 Sample App.

See the CapitolHillCoffee sample app for an example of a complete app that displays coffee shops on a map. The sample is available as part of the Apps & Games Services SDKs. For details about downloading, registering, and compiling the sample, see Using the Amazon Maps API v2 Sample App.