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

  1. Android Studio Arctic Fox oder höher ist erforderlich. Falls noch nicht geschehen, müssen Sie diese Version von Android Studio herunterladen und installieren.
  2. Es muss mindestens Version 7.0 des Android-Gradle-Plug-ins in Android Studio verwendet werden.

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, Maven-Repository von Google und 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.
    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:
    android {
        compileSdk 34
    
        defaultConfig {
            minSdk 19
            // ...
        }

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 (nur in englischer Sprache verfügbar).

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.
    MAPS_API_KEY=YOUR_API_KEY
  6. Speichern Sie die Datei.
  7. 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}" />
  8. 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 the name of your local properties file (either local.properties or local.defaults.properties depending on how you created the project), 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.*"
    }
            

Hinweis: Für den API-Schlüssel wird com.google.android.geo.API_KEY als Metadatenname empfohlen (siehe oben). Ein Schlüssel mit diesem Namen kann zur Authentifizierung bei mehreren Google Maps-basierten APIs auf der Android-Plattform verwendet werden, einschließlich Maps SDK for Android. Aus Gründen der Abwärtskompatibilität unterstützt die API auch den Namen com.google.android.maps.v2.API_KEY. Für diesen alten Namen wird nur die Authentifizierung bei Version 2 der Android Maps API unterstützt. In der App können nicht beide Metadatennamen für den API-Schlüssel angegeben werden, sondern nur jeweils einer. Falls beide angegeben werden, gibt die API eine Ausnahme aus.

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 dem der genaue Gerätestandort angegeben wird, und ACCESS_COARSE_LOCATION, mit dem 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.