This page describes how to configure an Android Studio project to use the Maps SDK for Android without using the Google Maps template that is detailed in the Quickstart.
The Google Maps template automatically configures and adds a basic map to a new Android Studio project. However, you can also add a map to an Android project that uses a different Android Studio template. To do so, you need to manually configure your project and then add the map.
Step 1: Set up Android Studio
- Android Studio Arctic Fox or later is required. If you haven't already done so, download and install it.
- Ensure that you are using the Android Gradle plugin version 7.0 or later in Android Studio.
Step 2. Set up the SDK
The Maps SDK for Android library is available through Google's Maven repository. To add the SDK to your app, do the following:
- In your top-level
settings.gradle
file, include the Gradle plugin portal, Google Maven repository, and Maven central repository under thepluginManagement
block. ThepluginManagement
block must appear before any other statements in the script.pluginManagement { repositories { gradlePluginPortal() google() mavenCentral() } }
- In your top-level
settings.gradle
file, include the Google's Maven repository and Maven central repository under thedependencyResolutionManagement
block:dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() } }
- In your module-level
build.gradle
file, add the Google Play services dependency for the Maps SDK for Android.dependencies { // Maps SDK for Android implementation 'com.google.android.gms:play-services-maps:18.2.0' }
- In your module-level
build.gradle
file, setcompileSdk
andminSdk
to the following values:android { compileSdk 31 defaultConfig { minSdk 19 // ... }
Step 3: Add your API key to the project
This section describes how to store your API key so that it can be securely referenced by
your app. You should not check your API key into your version control system, so we recommend
storing it in the secrets.properties
file, which is located in the root directory of your
project. For more information about the secrets.properties
file, see
Gradle properties files.
To streamline this task, we recommend that you use the Secrets Gradle Plugin for Android.
To install the Secrets Gradle Plugin for Android in your Google Maps project:
-
In Android Studio, open your project-level
build.gradle
file and add the following code to thedependencies
element underbuildscript
.Groovy
buildscript { dependencies { classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1" } }
Kotlin
buildscript { dependencies { classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1") } }
-
Open your module-level
build.gradle
file and add the following code to theplugins
element.Groovy
plugins { // ... id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' }
Kotlin
plugins { id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") }
- Save the file and sync your project with Gradle.
-
Open the
secrets.properties
in your project level directory, and then add the following code. ReplaceYOUR_API_KEY
with your API key.MAPS_API_KEY=YOUR_API_KEY
- Save the file.
-
In your
AndroidManifest.xml
file, go tocom.google.android.geo.API_KEY
and update theandroid:value attribute
as follows:<meta-data android:name="com.google.android.geo.API_KEY" android:value="${MAPS_API_KEY}" />
-
Optionally edit the properties of the plugin to specify a different secrets file or other properties. In Android Studio, open your project-level
build.gradle
file and edit thesecrets
property:Groovy
secrets { // Optionally specify a different file name containing your secrets. // The plugin defaults to "local.properties" propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
Kotlin
secrets { // Optionally specify a different file name containing your secrets. // The plugin defaults to "local.properties" propertiesFileName = "secrets.properties" // A properties file containing default secret values. This file can be // checked in version control. defaultPropertiesFileName = "local.defaults.properties" // Configure which keys should be ignored by the plugin by providing regular expressions. // "sdk.dir" is ignored by default. ignoreList.add("keyToIgnore") // Ignore the key "keyToIgnore" ignoreList.add("sdk.*") // Ignore all keys matching the regexp "sdk.*" }
Note: As shown above,
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 name com.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.
Step 4: Update the app manifest
This section describes the settings to add to your
AndroidManifest.xml
file.
Google Play services version number
Add the following declaration within the application
element. This embeds
the version of Google Play services that the app was compiled with.
<meta-data
android:name="com.google.android.gms.version"
android:value="@integer/google_play_services_version" />
Location permission
If your app needs to access the user's location, you need to request the
location permission in your AndroidManifest.xml
file. The options are
ACCESS_FINE_LOCATION
, which provides the precise device location, and
ACCESS_COARSE_LOCATION
, which is less precise. For details, see the
location data guide.
To request the ACCESS_FINE_LOCATION
permission, add this code to the
manifest
element:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
External storage permission
If you're targeting version 8.3 or later of the Google Play services SDK,
you don't need the WRITE_EXTERNAL_STORAGE
permission. If you're targeting
earlier versions of the Google Play services SDK, you must request the
WRITE_EXTERNAL_STORAGE
permission, in the manifest
element.
<uses-permission
android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
Apache HTTP Legacy library
If you are using com.google.android.gms:play-services-maps:16.0.0
or below and
your app is targeting API level 28 (Android 9.0) or above, you must include
the following declaration within the <application>
element of
AndroidManifest.xml
. Otherwise, skip this declaration.
<uses-library
android:name="org.apache.http.legacy"
android:required="false" />
Step 5: 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 4.0 or higher and includes the Google APIs.
- To use an Android device, follow the instructions at Run apps on a hardware device.
- To use an Android emulator, you can create a virtual device and install the emulator by using the Android Virtual Device (AVD) Manager that comes with Android Studio.
Step 6: Optionally check for Play Service support
Maps SDK for Android requires that the device on which you deploy your app has the Google Play services installed. Google provides a method that you can call from your app to check. For more information, see Check whether Google Play services is installed.
Next steps
Once your project is configured, you can add a map.