Maps SDK for Android – Kurzanleitung

Auf dieser Seite wird beschrieben, wie Sie mit der Google Maps Views-Vorlage für Android Studio eine Android-App erstellen, in der eine Karte zu sehen ist. Wenn Sie ein bestehendes Android Studio-Projekt konfigurieren möchten, empfehlen wir den Artikel Android Studio-Projekt einrichten.

Hinweis: In dieser Kurzanleitung wird die Vorlage Google Maps Views Activity verwendet, mit der ein XML-Layout mit einem SupportMapFragment erstellt wird. Wenn Sie Ihre UI mit Jetpack Compose erstellen, verwenden Sie stattdessen die Maps Compose-Bibliothek.

Diese Kurzanleitung ist für Entwickler vorgesehen, die mit den Grundlagen der Android-Entwicklung mit Java oder Kotlin vertraut sind.

Die Entwicklungsumgebung

Wir empfehlen, die neueste stabile Version von Android Studio und des Android Gradle-Plug-ins zu verwenden.

Hinweis: Wenn in Ihrer Entwicklungsumgebung eine andere Version von Android Studio oder Gradle verwendet wird, müssen Sie die Schritte möglicherweise entsprechend anpassen. Weitere Informationen zu Android Studio- und Gradle-Versionen sind im Abschnitt zur Kompatibilität zwischen Android-Gradle-Plug-in und Android Studio verfügbar.

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 6.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 Gerätemanager installieren, der in Android Studio enthalten ist.
  Hinweis: Wenn Sie einen Android Emulator verwenden möchten, müssen Sie ein Geräteprofil auswählen, bei dem in der Spalte Play Store ein Google Play-Symbol angezeigt wird. Das Symbol weist darauf hin, dass die entsprechenden Profile vollständig mit CTS kompatibel sind und Systemimages verwenden dürfen, die die Google Play Store App enthalten.

In Android Studio ein Google Maps-Projekt erstellen

1. Öffnen Sie Android Studio und klicken Sie im Fenster Welcome to Android Studio (Willkommen bei Android Studio) auf New Project (Neues Projekt).

2. Klicken Sie im Fenster New Project (Neues Projekt) in der Kategorie Phone and Tablet (Smartphone und Tablet) auf No Activity (Keine Aktivität) und dann auf Next (Weiter).

3. Füllen Sie das Formular New Project aus:

   • Legen Sie für Language Java oder Kotlin fest. Beide Sprachen werden im Maps SDK for Android vollständig unterstützt. Weitere Informationen zum Entwickeln von Android-Apps mit Kotlin

   • Geben Sie unter Minimum SDK eine SDK-Version an, die mit Ihrem Testgerät kompatibel ist. Sie müssen eine Version auswählen, die höher als die Mindestversion ist, die für das Maps SDK for Android, Version 20.0.x, erforderlich ist. Das ist Android API-Level 23 (Marshmallow, Android 6.0) oder höher. Weitere Informationen finden Sie in den Versionshinweisen, um die neuesten Informationen zu den SDK-Versionsanforderungen zu erhalten.

     Hinweis: Falls Sie nicht sicher sind, welche SDK-Version Sie auswählen sollen, klicken Sie auf den Link Help me choose (Auswahlhilfe), um sich Distributionsinformationen für unterstützte Android SDKs anzeigen zu lassen. Wenn Sie beispielsweise Android API Level 23 (Marshmallow, Android 6.0) auswählen, sollte Ihre App auf über 99% der Android-Geräte ausgeführt werden können.

   • Legen Sie Build configuration language (Sprache für die Build-Konfiguration) auf Kotlin DSL oder Groovy DSL fest. Im Folgenden finden Sie Snippets für beide Sprachen.

4. Klicken Sie auf Finish (Fertigstellen).

   Über Android Studio wird Gradle gestartet und das Projekt erstellt. Das kann einige Zeit dauern.

5. Fügen Sie die Google Maps Views Activity hinzu:

   1. Klicken Sie in Ihrem Projekt mit der rechten Maustaste auf den Ordner app.

   2. Wählen Sie New > Google > Google Maps Views Activity aus.

      

   3. Setzen Sie im Dialogfeld New Android Activity ein Häkchen in das Kästchen für Launcher Activity.

   4. Klicken Sie auf Finish.

      Weitere Informationen finden Sie unter Code aus einer Vorlage hinzufügen.

6. Wenn der Build fertig ist, werden die Dateien AndroidManifest.xml und MapsActivity von Android Studio geöffnet. Ihre Aktivität hat möglicherweise einen anderen Namen, aber abgesehen davon wird nichts daran geändert.

   Achtung: Die Datei AndroidManifest.xml enthält eine Anleitung, wie ein Google Maps API-Schlüssel abgerufen und anschließend in der Datei local.properties abgelegt werden kann. Fügen Sie der Datei local.properties nicht Ihren eigenen API-Schlüssel hinzu. Folgen Sie stattdessen der Anleitung unter Google Cloud-Projekt einrichten und API-Schlüssel in die App einfügen, um Ihren API-Schlüssel mit dem Secrets Gradle-Plug-in für Android in einer separaten secrets.properties Datei zu speichern.

Google Cloud-Projekt einrichten

Klicken Sie auf die Tabs unten, um die Einrichtung in der Cloud Console vorzunehmen:

Schritt 1

Cloud Console

1. Klicken Sie in der Google Cloud Console auf der Seite der Projektauswahl auf Projekt erstellen , um ein neues Cloud -Projekt einzurichten.

   Zur Projektauswahl

2. Die Abrechnung für das Cloud-Projekt muss aktiviert sein. Das können Sie hier überprüfen.

   Google Cloud bietet einen kostenlosen Testzeitraum. Dieser endet entweder nach 90 Tagen oder wenn im Konto Kosten in Höhe von 300 $ angefallen sind – je nachdem, welcher Fall zuerst eintritt. Eine Kündigung ist jederzeit möglich. Weitere Informationen finden Sie unter Guthaben auf dem Rechnungskonto und Abrechnung.

Cloud SDK

gcloud projects create "PROJECT"

Weitere Informationen zum Google Cloud SDK, zur Cloud SDK-Installation und zu folgenden Befehlen:

• gcloud projects create

Hinweis: Falls Sie die in dieser Übung erstellten Ressourcen nicht behalten möchten, richten Sie ein neues Projekt ein, statt ein vorhandenes auszuwählen. Das neue Projekt können Sie einfach löschen, wenn Sie fertig sind. Dadurch werden alle damit verknüpften Ressourcen entfernt.

Schritt 2

Damit Sie die Google Maps Platform verwenden können, müssen Sie die APIs und SDKs aktivieren, die Sie in Ihrem Projekt nutzen möchten.

Cloud Console

Maps SDK for Android aktivieren

Cloud SDK

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

Weitere Informationen zum Google Cloud SDK, zur Cloud SDK-Installation und zu folgenden Befehlen:

• gcloud services enable
• gcloud services disable

Schritt 3

Dieser Schritt behandelt nur die Erstellung des API-Schlüssels. Wenn Sie Ihren API-Schlüssel in der Produktionsumgebung verwenden, sollten Sie ihn außerdem unbedingt einschränken. Weitere Informationen zur Vorgehensweise finden Sie auf der Seite API-Schlüssel verwenden.

Der API-Schlüssel ist eine eindeutige Kennung. Damit werden die mit Ihrem Projekt verknüpften Anfragen zu Nutzungs- und Abrechnungszwecken authentifiziert. Mit Ihrem Projekt muss mindestens ein API-Schlüssel verknüpft sein.

So erstellen Sie einen API-Schlüssel:

Cloud Console

1. Rufen Sie die Seite Google Maps Platform > Anmeldedaten auf.

   Zur Seite „Anmeldedaten“

2. Klicken Sie auf der Seite Anmeldedaten auf Anmeldedaten erstellen > API-Schlüssel.
   Im Dialogfeld API-Schlüssel erstellt wird der neu erstellte API-Schlüssel angezeigt.
3. Klicken Sie auf Schließen.
   Der neue API-Schlüssel wird auf der Seite Anmeldedaten unter API-Schlüssel aufgeführt.
   Es empfiehlt sich, den API-Schlüssel einzuschränken, bevor Sie ihn in der Produktionsumgebung verwenden.

Cloud SDK

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Weitere Informationen zum Google Cloud SDK, zur Cloud SDK-Installation und zu folgenden Befehlen:

• gcloud services api-keys create

API-Schlüssel in die App einfügen

In diesem Abschnitt wird beschrieben, wie Sie Ihren API-Schlüssel speichern, damit er von Ihrer App sicher 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 und diese Datei von der Versionsverwaltung auszuschließen. Weitere Informationen zu Gradle Eigenschaftsdateien finden Sie unter Gradle properties files.

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

So installieren Sie das Secrets Gradle-Plug-in für Android und speichern Ihren API-Schlüssel:

1. Öffnen Sie in Android Studio die Datei build.gradle.kts oder build.gradle auf oberster Ebene und fügen Sie den folgenden Code in den Block plugins ein.

   Kotlin

   plugins {
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
   }

   Groovy

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

2. Öffnen Sie die Datei auf Modulebene build.gradle.kts oder build.gradle und fügen Sie den folgenden Code in das plugins Element ein.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Groovy

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

3. Wenn Sie Android Studio, synchronisieren Sie Ihr Projekt mit Gradle.
4. Öffnen Sie die Datei secrets.properties im Verzeichnis der obersten Ebene, und fügen Sie den folgenden Code ein. Ersetzen Sie YOUR_API_KEY durch Ihren API-Schlüssel. Stellen Sie sicher, dass Sie secrets.properties zu Ihrer .gitignore Datei hinzufügen (oder sie auf andere Weise aus Ihrem Versions verwaltungssystem ausschließen), damit Sie Ihren API-Schlüssel nicht in die Versionsverwaltung einchecken.
   Hinweis: Wenn die Datei secrets.properties nicht vorhanden ist, erstellen Sie sie im selben Ordner wie die Datei local.properties.

   MAPS_API_KEY=YOUR_API_KEY

5. 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.

   Hinweis:Geben Sie den Code genau wie hier gezeigt ein. Ersetzen Sie DEFAULT_API_KEY nicht durch Ihren API-Schlüssel.

   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.

6. Suchen Sie in der Datei AndroidManifest.xml nach com.google.android.geo.API_KEY und aktualisieren Sie das Attribut android:value so:

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

   Hinweis: com.google.android.geo.API_KEY ist der empfohlene Metadatenname für den API-Schlüssel. Ein Schlüssel mit diesem Namen kann zur Authentifizierung bei mehreren Google Maps-basierten APIs auf der Android-Plattform verwendet werden, einschließlich des 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 Google 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.

7. Öffnen Sie in Android Studio die Datei auf Modulebene build.gradle.kts oder build.gradle und bearbeiten Sie die Eigenschaft secrets. Wenn die Eigenschaft secrets nicht vorhanden ist, fügen Sie sie hinzu.

   Bearbeiten Sie die Attribute des Plug-ins, um propertiesFileName auf "secrets.properties" festzulegen, defaultPropertiesFileName auf "local.defaults.properties" festzulegen und alle anderen Attribute festzulegen.

   Kotlin

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "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 root directory (the same folder as the root local.properties file).
       // 2. Add this line, where YOUR_API_KEY is your API key:
       //        MAPS_API_KEY=YOUR_API_KEY
       propertiesFileName = "secrets.properties"
   
       // A properties file containing default secret values. This file can be
       // checked in version control.
       defaultPropertiesFileName = "local.defaults.properties"
   }

Hinweis: Wenn Logcat E/Google Maps Android API: Authorization failure meldet, prüfen Sie, ob Maps SDK for Android in Ihrem Google Cloud-Projekt aktiviert ist und ob der API-Schlüssel in Ihrer zusammengeführten Datei AndroidManifest.xml gültig ist.

Code ansehen

Überprüfen Sie den Code aus der Vorlage. Sehen Sie sich insbesondere die folgenden Dateien in Ihrem Android Studio-Projekt an.

Datei zur Google Maps-Aktivität

Dies ist die Hauptaktivität für die App. Sie enthält den Code zum Verwalten und Anzeigen der Karte. Der Name der Datei, die die Aktivität definiert, ist standardmäßig MapsActivity.java. Wenn Kotlin als Sprache festgelegt ist, heißt sie MapsActivity.kt.

Die Hauptelemente der Google Maps-Aktivität:

• Über das SupportMapFragment-Objekt wird der Lebenszyklus der Karte verwaltet. Es ist das übergeordnete Element der App-UI.

• Über das GoogleMap-Objekt ist der Zugriff auf die Kartendaten und die Kartenansicht möglich. Dies ist die wichtigste Klasse des Maps SDK for Android. Im Leitfaden zu Kartenobjekten werden die Objekte SupportMapFragment und GoogleMap genauer beschrieben.

• Mit der moveCamera Funktion wird die Karte auf die LatLng Koordinaten von Sydney (Australien) zentriert. Die ersten Einstellungen, die beim Hinzufügen einer Karte konfiguriert werden, sind in der Regel die Kartenposition und die Kameraeinstellungen, etwa Blickwinkel, Kartenausrichtung und Zoomstufe. Weitere Informationen finden Sie im Handbuch zu Kamera und Ansicht.

• Mit der Funktion addMarker wird an den Koordinaten von Sydney eine Markierung hinzugefügt. Weitere Informationen finden Sie im Leitfaden Marker.

Kotlin

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

Java

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

Gradle-Datei des Moduls

Die Datei build.gradle.kts oder build.gradle auf Modulebene enthält die folgende Kartenabhängigkeit, die für das Maps SDK for Android erforderlich ist.

Kotlin

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

Groovy

dependencies {

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

Wenn Ihr Projekt einen Gradle-Versionskatalog (gradle/libs.versions.toml) verwendet, definieren Sie die play-services-maps Abhängigkeit in libs.versions.toml:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

Hinweis: Die genaue Version kann sich je nach aktueller Version des Maps SDK for Android ändern.

Weitere Informationen zum Verwalten der Kartenabhängigkeit finden Sie im Leitfaden zur Versionsverwaltung.

XML-Layoutdatei

Die Datei activity_maps.xml ist die XML-Layoutdatei, mit der die Strukturen der App-UI definiert werden. Sie befindet sich im Verzeichnis res/layout. In der Datei activity_maps.xml ist ein Fragment deklariert, das die folgenden Elemente enthält:

• tools:context legt die Standardaktivität des Fragments auf MapsActivity fest. Die entsprechende Definition ist in der Datei zu den Google Maps-Aktivitäten enthalten.
• android:name legt den Klassennamen des Fragments auf SupportMapFragment fest. Dies ist der Fragmenttyp, der in der Datei zur Maps-Aktivität verwendet wird.

Die XML-Layoutdatei enthält folgenden Code:

<fragment xmlns: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" />

App bereitstellen und ausführen

Wenn die App korrekt programmiert ist und ausgeführt wird, ist dort nun eine Karte zu sehen, auf der Sydney in der Mitte liegt und markiert ist (wie im Screenshot oben dargestellt).

So können Sie die App bereitstellen und ausführen:

1. Klicken Sie in Android Studio auf die Menüoption Run oder das Wiedergabesymbol.
2. Wählen Sie dann das Gerät aus:
   • Wählen Sie das Android-Gerät aus, das mit Ihrem Computer verbunden ist,
   • Alternativ wählen Sie das Launch Emulator Optionsfeld und wählen Sie das von Ihnen eingerichtete virtuelle Gerät aus.
3. Klicken Sie dann auf OK. In Android Studio wird Gradle gestartet, um Ihre App zu erstellen. Die Ergebnisse werden dann auf Ihrem Gerät oder in Ihrem Emulator angezeigt. Es kann einige Minuten dauern, bis die App gestartet wird.

Nächste Schritte

• Karte konfigurieren: Auf dieser Seite wird beschrieben, wie Sie die Anfangs- und Laufzeiteinstellungen für die Karte konfigurieren, wie etwa Kameraposition, Kartentyp, UI-Komponenten und Touch-Gesten.

• Karte in Ihre Android-App einfügen (Kotlin): In diesem Codelab werden Sie Schritt für Schritt durch eine App geführt und erfahren, wie Sie einige Zusatzfunktionen des Maps SDK for Android verwenden.

• Maps Android KTX verwenden: Mit dieser Bibliothek mit Kotlin-Erweiterungen (Kotlin extensions, KTX) können Sie verschiedene Kotlin-Sprachfunktionen nutzen, während Sie das Maps SDK for Android verwenden.