Developer Console
Merci de votre visite. Cette page est disponible en anglais uniquement.

Get 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

Install the following on your development computer:

  • Android SDK
  • Any Android SDK system requirements
  • An IDE for Android development, such as Android Studio

While you can use the Amazon Maps API with any development environment, this guide demonstrates it using Android Studio. See Configure Android Studio for information about setting up the Android Studio development environment.

Set Up a Fire Tablet for Testing

If your Fire tablet is not set up for Android development, follow these steps:

  1. Go to Settings > Device Options > About Fire Tablet.
  2. Tap your Serial Number field seven times.
  3. Return to Device Options.
  4. Tap Developer options.
  5. Set Developer options and USB debugging to ON.
  6. Connect your Fire tablet to your computer using its cable.

Step 2: Download the Amazon Maps SDK Support Library

To use the Amazon Maps SDK in your project, you must download it and add the Amazon Maps SDK Support Library 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.

Step 3: Configure Your Project in Android Studio

Use the provided .AAR file with Android Studio. The library should be added to your project's \lib\aar folder. You can integrate the AAR file using either of the following options:

Option A: Configure your Project Without Using a Repository

Following these steps is the simplest way to configure your project in Android Studio.

  1. Set the minimum Android SDK version (android:minSdkVersion) to 21. You can also set the target SDK version (android:targetSdkVerion) to 27.
  2. Go to File > New > New Module…
  3. Click Import .JAR/.AAR Package, and then click Next.
  4. Navigate to your amazon-maps-api-v2.aar file and click Finish.
  5. Wait until your app syncs.
  6. Add the following line under the dependencies of your build.gradle (Module.app):

    implementation fileTree(dir: 'libs', include: ['*.aar'])
    
  7. On your right side, click Sync now.

    Note that in the module-level build.gradle file, you can use this approach alternatively to step 6:

    implementation(name:'amazonmapsapiv2_lib', ext:'aar')
    

    In that case, update your project-level build.gradle repositories like this:

    repositories {
          flatDir {
                  dirs 'libs'
          }
    }
    

Option B: Use a Local Maven Repository

If you prefer to install the Amazon Maps SDK Support Library in a local Maven repository, you must reference it as a Gradle dependency. To install the Amazon Maps SDK .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. 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.

  3. 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:

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

    implementation('com.amazon.android:amazon-maps-api:2.5')
    

    For example:

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

    include ':amazonmapsapiv2_lib'
    
  6. If the project was an Amazon Maps SDK v2.0 project that you imported from Eclipse (such as the sample app), 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.

Step 4: Configure Your Android Manifest

To use Amazon Maps API features, you must update the AndroidManifest.xml file of your app by following the instructions in the following two sections:

Update App Permissions

In this step you must include all the necessary permissions in your Android manifest. At a minimum, you need the following permissions:

  • android.permission.INTERNET
  • android.permission.ACCESS_NETWORK_STATE
  • android.permission.READ_EXTERNAL_STORAGE
  • android.permission.WRITE_EXTERNAL_STORAGE

For developing localized experiences, you must also add these permissions:

  • android.permission.ACCESS_COARSE_LOCATION
  • android.permission.ACCESS_FINE_LOCATION

For information about Fire OS API levels, see Fire OS Overview.

Enable 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.

For ANT, add this line in your project's project.properties file:

manifestmerger.enabled=true

In case you are disabling manifest merging, add the following lines to the <application> element in your AndroidManifest.xml:

<uses-feature android:name="com.fireos.sdk.amazon_maps" android:required="true" />
<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" />

Step 5: 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. For details about downloading, registering, and compiling the sample, see Using the 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;
    }
}

Next Steps

See Register and Test Your App.