Android Studio-Projekt einrichten

Auf dieser Seite wird erläutert, wie ein bestehendes Android Studio-Projekt für das Maps SDK for Android konfiguriert werden kann, und zwar ohne die in der Kurzanleitung beschriebene Google Maps-Vorlage.

Mit der Vorlage wird ein neues Android Studio-Projekt automatisch konfiguriert. Gleichzeitig wird auch eine Basiskarte eingebunden. Sie haben jedoch auch die Möglichkeit, eine Karte in ein Android-Projekt einzubinden, für die eine andere Android Studio-Vorlage verwendet wird. Dazu müssen Sie Ihr Projekt manuell konfigurieren und dann die Karte hinzufügen.

Schritt 1: Android Studio einrichten

In diesem Dokument wird eine Entwicklungsumgebung mit Android Studio Hedgehog und Version 8.2 des Android-Gradle-Plug-ins beschrieben.

Schritt 2: SDK einrichten

Die Maps SDK for Android-Bibliothek ist über das Maven-Repository von Google verfügbar. So fügen Sie das SDK der App hinzu:

  1. Fügen Sie in der Datei settings.gradle auf oberster Ebene das Portal für Gradle-Plug-ins, das Maven-Repository von Google und das Maven Central Repository unter dem pluginManagement-Block ein. Der pluginManagement-Block muss vor allen anderen Anweisungen im Script eingefügt werden. 
    pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  2. Fügen Sie in der Datei settings.gradle auf oberster Ebene das Maven-Repository von Google und das Maven Central Repository unter dem dependencyResolutionManagement-Block ein: 
    dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}
  3. Fügen Sie in der Datei build.gradle auf Modulebene die Abhängigkeit für Google Play-Dienste für das Maps SDK for Android ein.

    Groovy

    dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

    Kotlin

    dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:18.2.0")
}
  4. Legen Sie in der Datei build.gradle auf Modulebene für compileSdk und minSdk die folgenden Werte fest:

    Groovy

    android {
    compileSdk 34

    defaultConfig {
        minSdk 19
        // ...
    }
}

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 19
        // ...
    }
}
  5. Fügen Sie im Abschnitt buildFeatures Ihrer build.gradle-Datei auf Modulebene die Klasse BuildConfig ein, die verwendet werden kann, um auf Metadatenwerte zuzugreifen, die später in diesem Verfahren definiert werden:

    Groovy

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

    Kotlin

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

Schritt 3: API-Schlüssel zum Projekt hinzufügen

In diesem Abschnitt wird beschrieben, wie Sie Ihren API-Schlüssel speichern, damit er von Ihrer App sicherer referenziert werden kann. Er sollte nicht in Ihrem Versionsverwaltungssystem eingecheckt werden. Stattdessen empfehlen wir Ihnen, ihn im Stammverzeichnis Ihres Projekts in der Datei secrets.properties zu speichern. Weitere Informationen zur Datei secrets.properties finden Sie unter Gradle properties files.

Sie können das Secrets Gradle-Plug-in for Android verwenden, um diese Aufgabe zu optimieren.

So installieren Sie das Secrets Gradle-Plug-in für Android in Ihrem Google Maps-Projekt:

  1. Öffnen Sie in Android Studio die Datei build.gradle oder build.gradle.kts auf oberster Ebene und fügen Sie den folgenden Code in das dependencies-Element unter buildscript ein.

    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")
    }
}
  2. Öffnen Sie die Datei build.gradle auf Modulebene und fügen Sie den folgenden Code in das plugins-Element ein.

    Groovy

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

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. In der Datei build.gradle auf Modulebene müssen targetSdk und compileSdk auf 34 gesetzt sein.
  4. Speichern Sie die Datei und synchronisieren Sie Ihr Projekt mit Gradle.
  5. Öffnen Sie die Datei secrets.properties im Verzeichnis der obersten Ebene und fügen Sie den folgenden Code ein. Ersetzen Sie dabei YOUR_API_KEY durch Ihren eigenen API-Schlüssel. Speichern Sie den Schlüssel in dieser Datei, da secrets.properties nicht in ein Versionsverwaltungssystem eingecheckt werden kann. 
    MAPS_API_KEY=YOUR_API_KEY
  6. Speichern Sie die Datei.

  7. Erstellen Sie die Datei local.defaults.properties im Verzeichnis der obersten Ebene, im selben Ordner wie die Datei secrets.properties, und fügen Sie folgenden Code ein.

    MAPS_API_KEY=DEFAULT_API_KEY

    Diese Datei ist ein Ersatzspeicherort für den API-Schlüssel, damit Builds nicht fehlschlagen, falls die Datei secrets.properties nicht gefunden wird. Das kann passieren, wenn Sie die App aus einem Versionsverwaltungssystem klonen, in dem secrets.properties nicht vorhanden ist, und noch keine lokale Datei secrets.properties erstellt haben, um Ihren API-Schlüssel bereitzustellen.

  8. Speichern Sie die Datei.
  9. Gehen Sie in der Datei AndroidManifest.xml zu com.google.android.geo.API_KEY und aktualisieren Sie das android:value attribute. Falls das <meta-data>-Tag nicht vorhanden ist, erstellen Sie es als untergeordnetes Element des <application>-Tags. 
    <meta-data
    android: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 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.

  10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

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

Schritt 4: App-Manifest aktualisieren

In diesem Abschnitt werden die Einstellungen erläutert, die in der Datei AndroidManifest.xml festgelegt werden müssen.

Versionsnummer der Google Play-Dienste

Fügen Sie die folgende Deklaration im application-Element ein. Damit wird die Version der Google Play-Dienste eingebettet, mit der die App kompiliert wurde.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Berechtigung zur Standortermittlung

Wenn Ihre App Zugriff auf den Standort des Nutzers benötigt, müssen Sie die Berechtigung zur Standortermittlung in der Datei AndroidManifest.xml anfordern. Zur Auswahl stehen ACCESS_FINE_LOCATION, mit der der genaue Gerätestandort angegeben wird, und ACCESS_COARSE_LOCATION, mit der ein weniger präziser Standort angegeben wird. Weitere Informationen finden Sie im Leitfaden zu Standortdaten.

Fügen Sie dem manifest-Element folgenden Code hinzu, um die Berechtigung ACCESS_FINE_LOCATION anzufordern:

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

Berechtigung zum externen Speichern

Wenn Sie für Ihre App Version 8.3 oder höher des Google Play Services SDK vorgeben, ist die Berechtigung WRITE_EXTERNAL_STORAGE nicht erforderlich. Wenn Sie eine ältere Version des Google Play Services SDK vorgeben, müssen Sie die Berechtigung WRITE_EXTERNAL_STORAGE anfordern, und zwar im manifest-Element.

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

Apache HTTP Legacy-Bibliothek

Wenn Sie com.google.android.gms:play-services-maps:16.0.0 oder niedriger verwenden und für Ihre App API-Level 28 (Android 9.0) oder höher angeben, müssen Sie die folgende Deklaration im <application>-Element von AndroidManifest.xml angeben. Andernfalls können Sie diese Deklaration weglassen.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

Schritt 5: Android-Gerät einrichten

Um eine App auszuführen, in der das Maps SDK for Android verwendet wird, müssen Sie sie auf einem Android-Gerät oder einem Android Emulator bereitstellen, das bzw. der auf Android 4.0 oder höher basiert und Google APIs enthält.

  • Wenn Sie ein Android-Gerät verwenden möchten, folgen Sie der Anleitung zum Ausführen von Apps auf einem Hardwaregerät: Run apps on a hardware device.
  • Wenn Sie einen Android Emulator verwenden möchten, können Sie ein virtuelles Gerät erstellen und den Emulator mit dem AVD Manager für virtuelle Android-Geräte installieren, der in Android Studio enthalten ist.

Schritt 6: Optional: Play-Dienste-Support prüfen

Für die Nutzung von Maps SDK for Android müssen auf dem Gerät, auf dem Sie Ihre App bereitstellen, Google Play-Dienste installiert sein. Google bietet eine Methode, die Sie über Ihre App aufrufen können, um dies zu prüfen. Weitere Informationen finden Sie unter Prüfen, ob die Google Play-Dienste installiert sind.

Nächste Schritte

Sobald Ihr Projekt konfiguriert ist, können Sie eine Karte hinzufügen.