AI-generated Key Takeaways

outlined_flag

• This guide provides a step-by-step process for integrating a Google Map into a new Android application using Android Studio.

• Developers need basic Android knowledge, Android Studio Hedgehog or later, and an Android device or emulator running Android 5.0+ with Google APIs.

• The process involves creating a new project, adding a Google Maps Activity, setting up a Google Cloud project with an API key, and securely adding the API key to the app.

• The resulting application will display a basic Google Map, allowing for further customization and interaction.

• Developers can find more advanced resources for map customization and features within the guide.

Create an Android app that displays a map by using the Google Maps Viewstemplate for Android Studio. If you have an existing Android Studio project thatyou'd like to set up, seeSet up an Android Studio project.

This quickstart is intended for developers who are familiar with basicAndroid development with Kotlin or Java.

About the development environment

This quickstart was developed usingAndroid StudioHedgehog and theAndroidGradle pluginversion 8.2.

Set up an Android device

To run an app that uses the Maps SDK for Android, you must deploy it to an Android device or Android emulator that is based on Android 5.0 or higher and includes the Google APIs.

• To use an Android device, follow the instructions atRun apps on a hardware device.
• To use an Android emulator, you can create a virtual device and install the emulator by using theAndroid Virtual Device (AVD) Manager that comes with Android Studio.Note:If you choose to use an Android emulator, ensure that you choose a device with thePlay icon,, displayed under thePlay Store column. This icon indicates that these profiles are fullyCTS compliant and may use system images that include the Play Store app:

  

Create a Google Maps project in Android Studio

The procedure to create a Google Maps project in Android Studio was changed inthe Flamingo and later releases of Android Studio.

1. Open Android Studio, and clickNew Project in theWelcome to Android Studio window.

2. In theNew Project window, under thePhone and Tablet category,selectNo Activity, and then clickNext.

3. Complete theNew Project form:

   • SetLanguage to Java or Kotlin. Both languages are fully supported bythe Maps SDK for Android. To learn more about Kotlin, seeDevelop Android apps with Kotlin.

   • SetMinimum SDK to an SDK version compatible with your test device.You must select a version greater than the minimum version required by theMaps SDK for Android version 19.0.x,which is Android API Level 21 ("Lollipop"; Android 5.0) or higher.See theRelease Notes forthe latest information on the SDK version requirements.

     Note: If you are unsure of what SDK version to choose, select theHelp me choose link to display distribution information for supportedAndroid SDKs. For example, if you chooseAndroid API Level 21 ("Lollipop"; Android 5.0), your app should run on over99% of Android devices.

   • Set theBuild configuration language to Kotlin DSL or Groovy DSL.Snippets for both build configurations languages are shown in the followingprocedures.

4. ClickFinish.

   Android Studio starts Gradle and builds the project. This may take some time.

5. Add theGoogle Maps Views Activity:

   1. Right-click on theapp folder in your project.

   2. SelectNew > Google > Google Maps Views Activity.

      

   3. In theNew Android Activity dialog box, select theLauncher Activity checkbox.

   4. SelectFinish.

      For more information, seeAdd code from a template

6. When the build is finished, Android Studio opens theAndroidManifest.xmlandMapsActivity files. Your activity may have a different name, but itis the one you configured during setup.

   Caution: TheAndroidManifest.xml file contains instructions on getting aGoogle Maps API key and then adding it to yourlocal.properties file.Donot add your API key to thelocal.properties file.Doing so stores your API key less securely. Instead, follow the instructionsinSet up your Google Cloud project to create a Cloud project andconfigure an API key.

Set up your Google Cloud project

Complete the required Cloud console setup steps by clickingthrough the following tabs:

gcloudprojectscreate"PROJECT"

gcloudservicesenable\--project"PROJECT"\"maps-android-backend.googleapis.com"

gcloudservicesapi-keyscreate\--project"PROJECT"\--display-name"DISPLAY_NAME"

Add the API key to your app

This section describes how to store your API key so that it can be securely referenced byyour app. You should not check your API key into your version control system, so we recommendstoring it in thesecrets.properties file, which is located in the root directory of yourproject. For more information about thesecrets.properties file, seeGradle properties files.

To streamline this task, we recommend that you use theSecrets Gradle Plugin for Android.

To install the Secrets Gradle Plugin for Android in your Google Maps project:

1. In Android Studio, open your top-levelbuild.gradle.kts orbuild.gradle file and add the following code to thedependencies element underbuildscript.

   Kotlin

   plugins {alias(libs.plugins.android.application) apply falsealias(libs.plugins.jetbrains.kotlin.android) apply falsealias(libs.plugins.kotlin.compose) apply falsealias(libs.plugins.secrets.gradle.plugin) apply false}

   Groovy

   buildscript {dependencies {classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"}}

2. Open your module-levelbuild.gradle.kts orbuild.gradle file and add the following code to theplugins element.

   Kotlin

   plugins{// ...alias(libs.plugins.secrets.gradle.plugin)}

   Groovy

   plugins {// ...id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'}

3. In your module-levelbuild.gradle.kts orbuild.gradle file, ensure thattargetSdk andcompileSdk are set to 34.
4. Sync your project with Gradle.
5. Open thesecrets.properties file in your top-level directory, and then add the following code. ReplaceYOUR_API_KEY with your API key. Store your key in this file becausesecrets.properties is excluded from being checked into a version control system.Note:If thesecrets.properties file does not exist, create it in the same folder as thelocal.properties file.

   MAPS_API_KEY=YOUR_API_KEY

6. Create thelocal.defaults.properties file in your top-level directory, the same folder as thesecrets.properties file, and then add the following code.

   Note:Enter the code as shown. Don't replaceDEFAULT_API_KEY with your API key.

   MAPS_API_KEY=DEFAULT_API_KEY

   The purpose of this file is to provide a backup location for the API key if thesecrets.properties file is not found so that builds don't fail. This can happen if you clone the app from a version control system which omitssecrets.properties and you have not yet created asecrets.properties file locally to provide your API key.

7. In yourAndroidManifest.xml file, go tocom.google.android.geo.API_KEY and update theandroid:value attribute. If the<meta-data> tag does not exist, create it as a child of the<application> tag.

   <meta-dataandroid:name="com.google.android.geo.API_KEY"android:value="${MAPS_API_KEY}"/>

   Note:com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the namecom.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

8. In Android Studio, open your module-levelbuild.gradle.kts orbuild.gradle file and edit thesecrets property. If thesecrets property does not exist, add it.

   Edit the properties of the plugin to setpropertiesFileName tosecrets.properties, setdefaultPropertiesFileName tolocal.defaults.properties, and set any other properties.

   Kotlin

   secrets{// To add your Maps API key to this project:// 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.// 2. Add this line, where YOUR_API_KEY is your API key://        MAPS_API_KEY=YOUR_API_KEYpropertiesFileName="secrets.properties"// A properties file containing default secret values. This file can be// checked in version control.defaultPropertiesFileName="local.defaults.properties"}

   Groovy

   secrets{// To add your Maps API key to this project:// 1. If the secrets.properties file does not exist, create it in the same folder as the local.properties file.// 2. Add this line, where YOUR_API_KEY is your API key://        MAPS_API_KEY=YOUR_API_KEYpropertiesFileName="secrets.properties"// A properties file containing default secret values. This file can be// checked in version control.defaultPropertiesFileName="local.defaults.properties"}

Look at the code

Examine the code supplied by the template. In particular, look at the followingfiles in your Android Studio project.

Maps activity file

The maps activity file is the mainactivity for the app, andcontains the code to manage and display the map. By default, the file thatdefines the activity is namedMapsActivity.java or if you set Kotlin as thelanguage for your app,MapsActivity.kt.

The main elements of the maps activity:

• TheSupportMapFragment object manages thelifecycle of the map and is the parent element of the app's UI.

• TheGoogleMap object provides access to the map data andview. This is the main class of the Maps SDK for Android. TheMap Objectsguide describes theSupportMapFragment andGoogleMap objects in moredetail.

• ThemoveCamera function centers the map at theLatLng coordinates for Sydney Australia. The first settings toconfigure when adding a map are usually the map location and camera settings;such as viewing angle, map orientation, and zoom level. See theCamera and View guide for details.

• TheaddMarker function adds a marker to the coordinates forSydney. See theMarkers guide for details.

Module Gradle file

The Modulebuild.gradle.kts file includes the following maps dependency, whichis required by the Maps SDK for Android.

dependencies{// Maps SDK for Androidimplementation(libs.play.services.maps)}

To learn more about managing the Maps dependency, seeVersioning.

XML layout file

Theactivity_maps.xml file is theXML layout file that defines thestructure of the app's UI. The file is located in theres/layout directory.Theactivity_maps.xml file declares a fragment that includes the followingelements:

• tools:context sets the default activity of the fragmenttoMapsActivity, which is defined in the maps activity file.
• android:name sets the class name of the fragment toSupportMapFragment, which is the fragment type used in the maps activityfile.

The XML layout file contains the following code:

<fragmentxmlns:android="http://schemas.android.com/apk/res/android"xmlns:map="http://schemas.android.com/apk/res-auto"xmlns:tools="http://schemas.android.com/tools"android:id="@+id/map"android:name="com.google.android.gms.maps.SupportMapFragment"android:layout_width="match_parent"android:layout_height="match_parent"tools:context=".MapsActivity"/>

Deploy and run the app

When you run the app successfully, it will display a map that is centered onSydney Australia with a marker on the city as seen in the following screenshot.

To deploy and run the app:

1. In Android Studio, click theRun menu option (or the play button icon) to run your app.
2. When prompted to choose a device, choose one of the following options:
   • Select the Android device that's connected to your computer.
   • Alternatively, select theLaunch emulator radio button and choose the virtual device that you set up.
3. ClickOK. Android Studio will start Gradle to build your app, and then display the results on your device or emulator. It can take several minutes before the app launches.

Next steps

• Set up a map: This documentdescribes how to set up the initial and runtime settings for your map, suchas the camera position, map type, UI components, and gestures.

• Add a map to your Android app (Kotlin): This codelabwalks you through an app that demonstrates some additional features of theMaps SDK for Android.

• Use the Maps Android KTX library:This Kotlin extensions (KTX) library lets you take advantage of severalKotlin language features while using the Maps SDK for Android.