AI-generated Key Takeaways

outlined_flag

• This guide explains how to manually configure an Android Studio project to use the Maps SDK for Android without the default Google Maps template.

• You will need to set up the Android SDK, add your API key securely, and update the app manifest with necessary permissions and settings.

• Ensure your Android device or emulator has Google Play services installed and is based on Android 5.0 or higher with the Google APIs.

• Optionally, you can implement a check within your app to ensure Google Play services are available on the user's device.

This page describes how to configure an Android Studio project to use theMaps SDK for Android without using the Google Maps templatethat is detailed in theQuickstart.

The Google Maps template automatically configures and adds a basic map to a newAndroid Studio project. However, you can also add a map to an Android projectthat uses a different Android Studio template. To do so, you need to manuallyconfigure your project and thenadd the map.

Step 1: Set up Android Studio

This document describes a development environment usingAndroid Studio Hedgehog and theAndroid Gradle pluginversion 8.2.

Step 2. Set up the SDK

The Maps SDK for Android library is available throughGoogle's Maven repository. Toadd the SDK to your app, do the following:

1. In your top-levelsettings.gradle.kts file, include theGradle plugin portal,Google Maven repository, andMaven central repository under thepluginManagement block. ThepluginManagement block must appear before any other statements in the script.

   pluginManagement {repositories {gradlePluginPortal()google()mavenCentral()}}

2. In your top-levelsettings.gradle.kts file, include theGoogle's Maven repository andMaven central repository under thedependencyResolutionManagement block:

   dependencyResolutionManagement {repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)repositories {google()mavenCentral()}}

3. In your module-levelbuild.gradle.kts orbuild.gradle file, add theGoogle Play services dependency for the Maps SDK for Android.

   Kotlin

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

   Groovy

   dependencies{// Maps SDK for Androidimplementation"com.google.android.gms:play-services-maps:19.0.0"}

4. In your module-levelbuild.gradle.kts orbuild.gradle file, setcompileSdk andminSdk to the following values:Note: Ensure thatcompileSdk is set to 34 or higher andminSdk is set to 21 or higher.

   Kotlin

   android{compileSdk=34defaultConfig{minSdk=21// ...}}

   Groovy

   android{compileSdk34defaultConfig{minSdk21// ...}}

5. In thebuildFeatures section of your module-levelbuild.gradle.kts orbuild.gradle file, add theBuildConfig class, which you can use to access metadata values defined later in this procedure:

   Kotlin

   android{// ...buildFeatures{buildConfig=true// ...}}

   Groovy

   android{// ...buildFeatures{buildConfigtrue// ...}}

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 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"}

Step 4: Update the app manifest

This section describes the settings to add to yourAndroidManifest.xml file.

Google Play services version number

Add the following declaration within theapplication element. This embedsthe version of Google Play services that the app was compiled with.

<meta-dataandroid: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 thelocation permission in yourAndroidManifest.xml file. The options areACCESS_FINE_LOCATION, which provides the precise device location, andACCESS_COARSE_LOCATION, which is less precise. For details, see thelocation data guide.

To request theACCESS_FINE_LOCATION permission, add this code to themanifest element:

<uses-permissionandroid:name="android.permission.ACCESS_FINE_LOCATION"/>

External storage permission

If you're targetingversion 8.3 or later of the Google Play services SDK,you don't need theWRITE_EXTERNAL_STORAGE permission. If you're targetingearlier versions of the Google Play services SDK, you must request theWRITE_EXTERNAL_STORAGEpermission, in themanifest element.

<uses-permissionandroid:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Apache HTTP Legacy library

If you are usingcom.google.android.gms:play-services-maps:16.0.0 or below andyour app is targeting API level 28 (Android 9.0) or above, you must includethe following declaration within the<application> element ofAndroidManifest.xml. Otherwise, skip this declaration.

<uses-libraryandroid: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 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:

  

Step 6: Optionally check for Play Service support

Maps SDK for Android requires that the device on which you deploy yourapp has the Google Play services installed. Google provides a method that youcan call from your app to check. For more information, seeCheck whether GooglePlay services is installed.

Next steps

Once your project is configured, you canadd a map.