Sample App with Amazon Maps API (v2.5)

The Amazon Maps SDK includes a sample app called CapitolHillCoffee that illustrates how to display coffee shops on a map.

• Downloading the Sample App
• Overview of the Sample Projects
• Sample App Demo
• Functionality in Each Project
• Step 1. Open a Sample App in Android Studio
• Step 2. Add the Maps SDK v2.5 into Your Project
• Step 3. Change the Package Name
• Step 4. Register Your App
• Step 5. Connect Your Computer to a Fire Tablet
• Step 6. Run Your App
• Troubleshooting
• Next Steps

Downloading the Sample App

The CapitolHillCoffee sample app is part of the Maps SDK Download. After you extract the zip file, the sample app is in the examples\CapitolHillCoffee folder.

Overview of the Sample Projects

The app has four separate projects in the CapitolHillCoffee folder, illustrating the CapitolHillCoffee app at different stages:

Sample App Demo

Here's a short video that shows the functionality in the full version (step4_final):

Functionality in Each Project

The following table describes the functionality in each project:

The projects build on each other, so project step1_display_map just contains the map. step2_add_my_location adds an icon that zooms in to the user's location on the map. step3_add_coffee_markers adds coffee shop icons on the map at various addresses. And step4_final adds address and phone number details about the coffee shops.

The code is cumulative with each project, building on the previous step's code. In this way, you can learn how to use the Maps API in a progressive way. Rather than starting out with the full code, you gradually increase the complexity with each step.

Step 1. Open a Sample App in Android Studio

To open a sample project:

1. Start Android Studio and select Open an existing Android Studio project at the startup dialog.

2. Browse to the build.gradle file under the project step (e.g., examples/CapitolHillCoffee/step1_display_map/build.gradle) you want to load, and then click Open.

   Android Studio loads the project and syncs the necessary dependencies with Gradle.

Step 2. Add the Maps SDK v2.5 into Your Project

Add the Amazon Maps SDK library to your project by following Getting Started - Step 4: Add the AAR File to Your Project in the Getting Started topic. The sample app already have a libs folder, so just copy the amazon-maps-api-v2.aar file into this directory. You must perform this step each time you load one of the example projects into Android Studio.

Step 3. Change the Package Name

The package name for the sample is com.example.amazon.capitolhillcoffee. You must change this to your own package name before registering the app (described in the next step), since all packages in the Amazon developer portal must have unique names. The app will not work (not even locally) until you register the package name, so this step is essential. To change the package name:

1. Switch to the Android view.
2. Click the Show Options Menu (gear icon) and clear the check mark next to Compact Middle Packages (if necessary).
3. Expand the java folders ( java > com > examples > amazon > capitolhillcoffee).
4. Right click example and choose Refactor > Rename. In the Rename dialog box, rename it to something unique, such as your name. Leave the scope at Project Files. Then click Refactor.
5. If a Refactoring Preview pane appears below, click Do Refactor.
6. Open the AndroidManifest.xml (inside manifests) and make sure all instances of the package (lines 12 and 24) reflect your new package name.
7. Click Sync now if prompted.
8. Go to File > Invalidate caches / restart to make sure Android Studio picks up the new package name.

Note that you will need to change the project name for each of the four sample projects.

Step 4. Register Your App

Before you can run the sample app, you need to register your app with the developer portal. Registration will provide the app with access to map tiles. Follow these steps in the Getting Started topic:

• Getting Started — Step 7: Retrieve your App's MD5 Signature from Android Studio
• Getting Started — Step 8: Add Your App in the Developer Console
• Getting Started — Step 9: Submit Your Debug Registration Request

Step 5. Connect Your Computer to a Fire Tablet

See Connect to Fire Tablet through ADB for details how to connect.

Step 6. Run Your App

1. Check that you have an app configuration to run your app:

   

2. If you don't have an app configuration, click the down arrow for the Edit Run/Debug configurations dialog (called "Maps" in the screenshot above) and select Edit Configurations.
3. Click the + in the upper-left corner and select Android App.
4. In the main window, customize the Name field, and then click OK. The configuration should appear in the menus.

5. Click the the Run 'app' button .

   Look at your tablet to see the app launch, and then explore the app.

Troubleshooting

If you run into issues, try the following:

• If your version of Android Studio is 4.x, make sure Gradle version is 4.0.0 in your build.file: classpath 'com.android.tools.build:gradle:4.0.0'.
• Many different errors can be fixed by running File > Invalidate Caches / Restart.

Next Steps

For more details about common Maps API tasks, see the following:

• Displaying an Interactive Map (v2.5)
• Drawing Markers and Objects on the Map (v2.5)