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.

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.

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 </code> element in your 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 Apps & Games Services SDKs and extract the files. The Maps v2 API SDK 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:

  1. Make sure you have installed Maven on your system. For details, see the Download Apache Maven page.
  2. Download the Apps & Games Services SDKs and extract the files, or follow the steps to download the SDK from the Android SDK Manager.
  3. 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.

  4. 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>_
    

To configure the dependencies for your project:

  1. Open or create your project in Android Studio.
  2. In the project-level build.gradle file, add mavenLocal() to the repositories section under allprojects. 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.

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

    compile project(':amazonmapsapiv2_lib')
    
  4. Also in the module-level build.gradle file for your app, add the following line to the dependencies section:

    compile('com.amazon.android:amazon-maps-api:2.0')
    

    For example:

    dependencies {
        <existing dependencies>
        compile('com.amazon.android:amazon-maps-api:2.0')
    }
    
  5. Edit the settings.gradle file and remove the line:

    include ':amazonmapsapiv2_lib'
    
  6. 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.
  7. 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

These steps assume you have already created your Android project. If not, first create the project using the android create project command.

  1. Download the Apps & Games Services SDKs and extract the files, or follow the steps to download the SDK from the Android SDK Manager.
  2. Note the path to the amazon-maps-api-v2_lib folder.
  3. Use the android update project command to update the amazon-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.

  4. Use the android update project command to update your project with a library reference to amazon-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
    
  5. 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 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.

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 phone or 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:

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.

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.