Android Studio-Projekt einrichten

Auf dieser Seite wird erläutert, wie Sie das Navigation SDK in Ihr Entwicklungsprojekt einbinden.

Das Navigation SDK in Ihr Projekt einbinden

Das Navigation SDK ist über das Maven-Repository von Google verfügbar. Sie können das SDK Ihrem Projekt entweder mit Ihrer Gradle-build.gradle- oder Maven-pom.xml-Konfiguration hinzufügen.

  1. Fügen Sie Ihrer Gradle- oder Maven-Konfiguration die folgende Abhängigkeit hinzu und ersetzen Sie den Platzhalter VERSION_NUMBER durch die gewünschte Version des Navigation SDK for Android.

    Gradle

    Fügen Sie der Datei build.gradle auf Modulebene Folgendes hinzu:

    dependencies {
        ...
        implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
}

    Maven

    Fügen Sie zum pom.xml Folgendes hinzu:

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.navigation</groupId>
    <artifactId>navigation</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

  2. Wenn Sie Abhängigkeiten haben, die das Maps SDK verwenden, müssen Sie die Abhängigkeit in jeder deklarierten Abhängigkeit ausschließen, die auf dem Maps SDK basiert.

    Gradle

    Fügen Sie der build.gradle auf oberster Ebene Folgendes hinzu:

    allprojects {
        ...
        // Required: you must exclude the Google Play service Maps SDK from
        // your transitive dependencies to make sure there won't be
        // multiple copies of Google Maps SDK in your binary, as the Navigation
        // SDK already bundles the Google Maps SDK.
        configurations {
            implementation {
                exclude group: 'com.google.android.gms', module: 'play-services-maps'
            }
        }
}

    Maven

    Fügen Sie zum pom.xml Folgendes hinzu:

    <dependencies>
  <dependency>
  <groupId>project.that.brings.in.maps</groupId>
  <artifactId>MapsConsumer</artifactId>
  <version>1.0</version>
    <exclusions>
      <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
      <exclusion>  <!-- declare the exclusion here -->
        <groupId>com.google.android.gms</groupId>
        <artifactId>play-services-maps</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
</dependencies>

Build konfigurieren

Nachdem Sie das Projekt erstellt haben, können Sie die Einstellungen für einen erfolgreichen Build und die Verwendung des Navigation SDK konfigurieren.

Lokale Eigenschaften aktualisieren

  • Öffnen Sie im Gradle Scripts folder (Gradle-Skriptordner) die Datei local.properties und fügen Sie android.useDeprecatedNdk=true hinzu.

Gradle-Build-Skript aktualisieren

  • Öffnen Sie die Datei build.gradle (Module:app) und folgen Sie der Anleitung unten, um die Einstellungen so zu aktualisieren, dass sie den Anforderungen für das Navigation SDK entsprechen. Sie sollten auch die Optimierungsoptionen festlegen.

    Erforderliche Einstellungen für das Navigation SDK

    1. Legen Sie minSdkVersion auf 23 oder höher fest.
    2. Legen Sie targetSdkVersion auf 34 oder höher fest.
    3. Fügen Sie eine dexOptions-Einstellung hinzu, die die javaMaxHeapSize erhöht.
    4. Legen Sie den Speicherort für zusätzliche Bibliotheken fest.
    5. Fügen Sie repositories und dependencies für das Navigation SDK hinzu.
    6. Ersetzen Sie die Versionsnummern in den Abhängigkeiten durch die neuesten verfügbaren Versionen.

    Optionale Einstellungen zur Verkürzung der Build-Zeit

    • Aktivieren Sie die Code- und Ressourcenreduzierung mit R8/ProGuard, um nicht verwendeten Code und Ressourcen aus Abhängigkeiten zu entfernen. Wenn der R8-/ProGuard-Schritt zu lange dauert, sollten Sie Multidex für die Entwicklung aktivieren.
    • Reduzieren Sie die Anzahl der Sprachübersetzungen im Build: Legen Sie während der Entwicklung resConfigs für eine Sprache fest. Legen Sie für den endgültigen Build resConfigs für die Sprachen fest, die Sie tatsächlich verwenden. Standardmäßig enthält Gradle Ressourcenstrings für alle Sprachen, die vom Navigation SDK unterstützt werden.

    Desugaring für Java 8-Unterstützung hinzufügen

    • Wenn Sie Ihre App mit dem Android-Gradle-Plug-in 4.0.0 oder höher erstellen, bietet das Plug-in Unterstützung für die Verwendung einer Reihe von Java 8-Sprach-APIs. Weitere Informationen finden Sie unter Unterstützung für Desugaring in Java 8. Im folgenden Beispiel-Snippet für ein Build-Skript sehen Sie, wie Sie Kompilierungs- und Abhängigkeitsoptionen festlegen.
    • Wir empfehlen, Gradle 8.4, das Android-Gradle-Plug-in in Version 8.3.0 und die Desugar-Bibliothek com.android.tools:desugar_jdk_libs_nio:2.0.3 zu verwenden. Dieses Setup ist mit dem Navigation SDK for Android ab Version 6.0.0 kompatibel.
    • Die Desugar-Bibliothek muss für das app-Modul und alle Module aktiviert werden, die direkt vom Navigation SDK abhängig sind.

Unten sehen Sie ein Beispiel für das Gradle-Build-Skript für die Anwendung. Sehen Sie sich die Beispiel-Apps an, um aktualisierte Abhängigkeiten zu finden, da die Version des Navigation SDK, die Sie verwenden, möglicherweise etwas neuer oder älter als diese Dokumentation ist.

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
        // Set this to the languages you actually use, otherwise you'll include resource strings
        // for all languages supported by the Navigation SDK.
        resConfigs "en"
        multiDexEnabled true
    }

    dexOptions {
        // This increases the amount of memory available to the dexer. This is required to build
        // apps using the Navigation SDK.
        javaMaxHeapSize "4g"
    }
    buildTypes {
        // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
        // The configuration is included transitively by depending on the Navigation SDK.
        // If the ProGuard step takes too long, consider enabling multidex for development work
        // instead.
        all {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.0.3'
}

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, 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.kts oder build.gradle auf oberster Ebene und fügen Sie den folgenden Code in das dependencies-Element unter buildscript ein.

    Kotlin

    plugins {
    alias(libs.plugins.android.application) apply false
    alias(libs.plugins.jetbrains.kotlin.android) apply false
    alias(libs.plugins.kotlin.compose) apply false
    alias(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. Öffnen Sie die Datei build.gradle.kts oder build.gradle auf Modulebene und fügen Sie dem plugins-Element den folgenden Code hinzu.

    Kotlin

    plugins {
    // ...
    alias(libs.plugins.secrets.gradle.plugin)
}

    Groovy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. In der Datei build.gradle.kts oder build.gradle auf Modulebene müssen targetSdk und compileSdk auf 34 gesetzt sein.
  4. 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. 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.

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

    Hinweis:Für den API-Schlüssel wird der Metadatenname com.google.android.geo.API_KEY empfohlen. Ein Schlüssel mit diesem Namen kann zur Authentifizierung bei mehreren Google Maps-basierten APIs auf der Android-Plattform verwendet werden, einschließlich des Navigation 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 Anwendung kann nur einer der Metadatennamen für den API-Schlüssel festgelegt werden. Falls beide angegeben werden, gibt die API eine Ausnahme aus.

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

    Bearbeiten Sie die Attribute des Plug-ins, um propertiesFileName auf secrets.properties, defaultPropertiesFileName auf local.defaults.properties 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 same folder as the 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 same folder as the 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"
}

Erforderliche Quellenangaben in Ihre App einfügen

Wenn Sie das Navigation SDK for Android in Ihrer App verwenden, müssen Sie Quellenangaben und Open-Source-Lizenzen in den Abschnitt mit den rechtlichen Hinweisen Ihrer App aufnehmen.

Den erforderlichen Attributionshinweis und die Open-Source-Lizenzen finden Sie in der ZIP-Datei des Navigation SDK for Android:

  • NOTICE.txt
  • LICENSES.txt

Wenn Sie Kunde von Mobility oder Fleet Engine Deliveries sind

Wenn Sie Kunde von Mobility oder Fleet Engine Deliveries sind, finden Sie Informationen zur Abrechnung in der Mobility-Dokumentation. Weitere Informationen zum Erfassen von Transaktionen finden Sie unter Abrechnung einrichten, Abrechenbare Transaktionen erfassen, Berichterstellung und Abrechenbare Transaktionen erfassen (Android).