Configuring Your Project (v2.0 - Deprecated)
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.
- Updating the AndroidManifest.xml
- Referencing the Amazon Maps API Support Library
- Verifying that Amazon Maps is Available on the Device
- Next Steps
Updating the AndroidManifest.xml
AndroidManifest.xml
file for your app.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.
For example:
<manifest ...>
<uses-sdk
android:minSdkVersion="15"
android:targetSdkVersion="19" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
...
</manifest>
For more information about Fire OS API levels, see Fire OS Overview.
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 AndroidManifest.xml
:
<uses-library android:name="com.amazon.application.compatibility.enforcer" android:required="false" />
<meta-data android:name="required_amazon_package:com.amazon.geo.mapsv2.services" android:value="@integer/amazon_maps_services_version" />
<meta-data android:name="amazon_maps_services_required" android:value="true" />
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:
-
Download the Maps SDK from the SDK Downloads page and extract the files. The Maps API v2.0 is in the
Apps-SDK.zip\Android\Maps\2.0\
folder. -
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:
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.
To install the Amazon Maps API .AAR to a local Maven repository:
- Make sure you have installed Maven on your system. For details, see the Download Apache Maven page.
- Download the Maps API and extract the files.
-
Note the full paths to these files:
amazon-maps-api-v2.aar amazon-maps-api-v2.pom
Both of these files are in the
\lib\aar
directory. -
At a command line, run the following Maven command. Provide the paths to the
.aar
and.pom
files as noted:mvn install:install-file -Dfile=_<path to amazon-maps-api-v2.aar>_ -DpomFile=_<path to amazon-maps-api-v2.pom>_
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-level
build.gradle
file, addmavenLocal()
to therepositories
section underallprojects
. For example:// Top-level build file where you can add configuration options common to all sub-projects/modules. ... allprojects { repositories { jcenter() mavenLocal() } }
If the
allprojects
item is missing, add it to the file.Note: An Android Studio project has multiplebuild.gradle
files. The project-levelbuild.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 differentbuild.gradle
files, see the "Project Build File" and "Module Build File" sections in Android Plug-in for Gradle. -
In the module-level
build.gradle
file for your app, remove the following line from thedependencies
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-level
build.gradle
file for your app, add the following line to thedependencies
section:compile('com.amazon.android:amazon-maps-api:2.0')
For example:
dependencies { <existing dependencies> compile('com.amazon.android:amazon-maps-api:2.0') }
-
Edit the
settings.gradle
file and remove the line:include ':amazonmapsapiv2_lib'
Note: This line might not exist. It is added when importing projects from Eclipse. - If the project was an Amazon Maps API v2 project that you imported from Eclipse (such as the sample app), use File Explorer to navigate to the project and delete the
amazonmapsapiv2_lib
directory. - At the top of the editor, in the yellow alert indicating that gradle files have changed, click Sync Now.
Configuring Your Project from the Command Line
ANT_HOME
, JAVA_HOME
, and PATH
environmental variables properly defined.These steps assume you have already created your Android project. If not, first create the project using the android create project
command.
- Download the Maps SDK and extract the files.
- Note the path to the
amazon-maps-api-v2_lib
folder. -
Use the
android update project
command to update theamazon-maps-api-v2_lib
project to your app's minimum Android SDK version. For example, the following command sets it to 15:android update project -p ../path/to/amazon-maps-api-v2_lib -t android-15
You can use the
android list targets
command to view a list of available platforms. -
Use the
android update project
command to update your project with a library reference toamazon-maps-api-v2_lib
. For example:android update project -t <target_ID> -p path/to/your/project -l path/to/amazon-maps-api-v2_lib
Running the above command adds this library reference to your project's
local.properties
file:android.library.reference.1=../path/to/amazon-maps-api-v2_lib
-
To build your project, run the following command from the root directory for your project:
ant debug
For general information on referencing libraries in Android projects using the command line, see the Referencing a Library Project section of Managing Projects from the Command Line.
Verifying that Amazon Maps is Available on the Device
The Amazon Maps API is supported on 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.
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:
import com.amazon.geo.mapsv2.util.AmazonMapsRuntimeUtil;
...
private boolean checkForAmazonMaps() {
// Check for the presence of Amazon Maps on the device
return AmazonMapsRuntimeUtil
.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:
@Override
protected void onCreate(Bundle savedInstanceState) {
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 message
int cr = AmazonMapsRuntimeUtil.isAmazonMapsRuntimeAvailable(this);
String msg = 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.
Next Steps
Before you can test your app on a Fire tablet, you need to register the device with the Amazon Appstore. This provides access to map tiles. See Registering and Testing Your Amazon Maps API v2 App.
If you are coding directly against the Amazon Maps API, refer to the Amazon Maps developer guides and references:
- Understanding the Amazon Maps API v2
- Displaying an Interactive Map with the Amazon Maps API v2
- Drawing Markers and Objects on the Map with the Amazon Maps API v2
- Amazon Maps API Reference
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 Maps SDK. For details about downloading, registering, and compiling the sample, see Using the Amazon Maps API v2 Sample App.
If you are migrating an app from Google Maps v2, make the additional code changes described in Migrating an App from Google Maps v2.
For additional help and information, see the Amazon Maps API Frequently Asked Questions.
Last updated: Mar 06, 2017