Getting Started with the Amazon Maps API (v2.5)

The following steps show you how to get started with the Amazon Maps API.

• Step 1: Set Up Your Development Environment
• Step 2: Set Up a Fire Tablet for Testing
• Step 3: Download the Amazon Maps SDK Support Library
• Step 4: Add the AAR File to Your Project
• Step 5: Configure Your Android Manifest
• Step 6: Verify Amazon Maps Availability on Device
  • Full MainActivity.java Example
• Step 7: Retrieve your App's MD5 Signature from Android Studio
• Step 8: Add Your App in the Developer Console
• Step 9: Submit Your Debug Registration Request
• Step 10: Load Your App on a Device for Testing
• Next Steps

Step 1: Set Up Your Development Environment

Install and configure Android Studio on your computer.If you already have Android Studio installed, update to the latest version (4.x) by going to Android Studio > Check for Updates.

Android Studio isn't required to use the Amazon Maps API, but if you're using another tool, make sure you have the Android SDK installed and other system requirements necessary for Android development.Also note that the instructions in this documentation will assume you're using Android Studio.

Step 2: Set Up a Fire Tablet for Testing

Follow the steps described in Connect to Fire Tablet through ADB to connect your Fire tablet to your computer.

See Fire Tablets that Support the Maps API v2.5 for more details on which Fire tablets you can use for testing.

Step 3: Download the Amazon Maps SDK Support Library

To use the Amazon Maps SDK in your project, you must download the SDK and add it to your project.The library is a Gradle-compatible project.To get the Maps SDK, go to SDK Downloads, download the Amazon Maps SDK version 2.5, and extract the files.For convenience, you can also download the SDK here:

Amazon Maps SDK (v2.5)

Step 4: Add the AAR File to Your Project

You add the AAR file (amazon-maps-api-v2.aar) to your Android project similar to how you would add other libraries to an Android project — by adding the AAR file into a libs folder.

1. In Android Studio, switch to the Project view.
2. Create a directory called libs at the root-level of your project (unless you already have a libs folder).To create this folder, right-click in your root directory and select New > Directory.Call it libs.
3. Copy and paste the amazon-maps-api-v2.aar file into this libs directory.(You can do this directly in the Android Studio user interface.) Click OK to confirm the Copy dialog prompt.

4. In your app's build.gradle file, reference the AAR file in the dependencies object:

   dependencies {
   implementation(name:'amazon-maps-api-v2', ext:'aar')
   }
   

5. In the same build.gradle file, add the following in repositories:

   repositories {
     google()
     jcenter()
     flatDir {
         dirs 'libs'
     }
   }
   

   Note that the SDK also includes a Maven POM file (amazon-maps-api-v2.pom) in case you want to load the SDK from a local Maven repository.The SDK is not available in a public Maven or JCenter repository.Instructions for loading the library from a local Maven repository are beyond the scope of this documentation.

Step 5: Configure Your Android Manifest

To use Amazon Maps API features, you must update app permissions listed in the AndroidManifest.xml file.At a minimum, you need the following permissions:

<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" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Step 6: Verify Amazon Maps Availability on Device

To ensure a good user experience, your app should check for the presence of the Amazon Maps API on the Fire tablet and adjust accordingly if it is not available.

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.If Amazon Maps is present, it returns ConnectionResult.SUCCESS.

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

import com.amazon.geo.mapsv2.util.AmazonMapsRuntimeUtil;
import com.amazon.geo.mapsv2.util.ConnectionResult;

...

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.

Full MainActivity.java Example

Here is an example MainActivity for app com.mytest.maps:

package com.mytest.maps;

import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import com.amazon.geo.mapsv2.util.AmazonMapsRuntimeUtil;
import com.amazon.geo.mapsv2.util.ConnectionResult;

public class MainActivity extends AppCompatActivity {

    @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 = " ConnectionResult = " + cr ;

        }
    }

    private boolean checkForAmazonMaps() {
        // Check for the presence of Amazon Maps on the device

        return AmazonMapsRuntimeUtil
                .isAmazonMapsRuntimeAvailable(this) == ConnectionResult.SUCCESS;
    }
}

Step 7: Retrieve your App's MD5 Signature from Android Studio

Every app must have its own registration.Debug and release builds require separate registration.To load map tiles during testing, you must register the debug build of your app.Registration for the release build is a separate process and occurs automatically when you submit your app, if you have already created a debug registration.With your registration request, you must provide the MD5 debug fingerprint.

To get your MD5 Signature:

1. Open your project in Android Studio.
2. Click the Gradle tab in the top-right corner.

3. Expand your app's entry, then expand Tasks, then android, and double click on signingReport.

   Android Studio generates a report in the status area at the bottom, where you will see MD5, SHA1, and SHA-256 info.Copy the MD5 value and store this info for future reference.

   Note: The keystore you configure in Android Studio must be different than the one used to sign the release APK published in the Amazon Appstore.Use the above process for testing purposes only.

If you aren't using Android Studio, you can extract the MD5 using the keytool utility from the JDK.

Step 8: Add Your App in the Developer Console

If you haven't yet added your app in the Developer Console, see Submitting Apps to the Amazon Appstore.

Step 9: Submit Your Debug Registration Request

Debug registration allows access to map tiles and geocoding in the debug build(s) of your app.To submit a debug registration request for apps that use the Amazon Maps API:

1. On the developer portal, open the list of your apps.
2. Click the app that you want to register.(If your app is not listed, first add the app to the portal.)
3. Click App Services in the left sidebar.
4. Click Maps.
5. Click Add a Debug Registration.
6. In the Package name box, enter the package name for your app.
7. In the Developer signature box, enter the MD5 fingerprint of the debug certificate that you obtained earlier.

8. Click Save.You see a response that says, "The application with package name "com.tomjoht.amazon.capitolhillcoffee" has been registered.

   Note that portions of the Amazon Maps API are provided by HERE North America, LLC or its affiliates ("HERE").By clicking "Save" to create a debug registration, you agree to the HERE Materials Terms and Conditions.

It takes time to propagate the registration to your device.After clicking Submit, allow one hour before testing the app that you registered (the registration process interacts with an external service as it processes).If a recently registered app does not show map tiles, you might need to allow more time for registration to take effect.

Register a debug build of your app for access to map tiles.You are required to register your debug app prior to uploading your release app.Release registration is a separate process and occurs automatically when you submit your app to the Amazon Appstore, if you have already created a debug registration

Step 10: Load Your App on a Device for Testing

Once you have registered your app, connect your device to a development computer for testing and debugging, and build your app.For information about using adb, see Connect to Fire Tablet through ADB.

Next Steps

See Sample App with Amazon Maps API (v2.5).