Konfigurowanie projektu w Android Studio

Na tej stronie znajdziesz informacje o integrowaniu pakietu SDK Nawigacji w projekcie programistycznym.

Dodawanie do projektu pakietu SDK nawigacji

Pakiet SDK Nawigacji jest dostępny w repozytorium Maven Google. Pakiet SDK możesz dodać do projektu, korzystając z konfiguracji Gradle build.gradle lub Maven pom.xml.

  1. Dodaj do konfiguracji Gradle lub Maven następującą zależność, zastępując miejsce zapełnienia VERSION_NUMBER żądaną wersją pakietu SDK nawigacji na Androida.

    Gradle

    Dodaj do pliku build.gradle na poziomie modułu te elementy:

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

    Maven

    Dodaj do pliku pom.xml te informacje:

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

  2. Jeśli masz jakiekolwiek zależności, które korzystają z pakietu Maps SDK, musisz wykluczyć tę zależność w przypadku każdej zadeklarowanej zależności, która korzysta z pakietu Maps SDK.

    Gradle

    Dodaj do pliku najwyższego poziomu build.gradle te informacje:

    allprojects {
        ...
        // Required: you must exclude the Google Play service Maps SDK from
        // your transitive dependencies. This is to ensure 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

    Dodaj do pliku pom.xml te informacje:

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

Konfigurowanie kompilacji

Po utworzeniu projektu możesz skonfigurować ustawienia, aby skompilować i użyć pakietu SDK nawigacji.

Aktualizowanie właściwości lokalnych

  • W folderze skryptów Gradle otwórz plik local.properties i dodaj android.useDeprecatedNdk=true.

Aktualizowanie właściwości gradle

  • W folderze skryptów Gradle otwórz plik gradle.properties i dodaj te elementy, jeśli ich jeszcze nie ma:

    1. android.useAndroidX=true
    2. android.enableJetifier=true

Zaktualizuj skrypt kompilacji Gradle

  • Otwórz plik build.gradle (Module:app) i zastosuj podane niżej wskazówki, aby zaktualizować ustawienia i spełnić wymagania dotyczące pakietu SDK nawigacji. Możesz też skonfigurować opcje optymalizacji.

    Wymagania dotyczące ustawień pakietu SDK do nawigacji

    1. Ustaw wartość minSdkVersion na 23 lub więcej.
    2. Ustaw wartość targetSdkVersion na 34 lub wyższą.
    3. Dodaj ustawienie dexOptions, które zwiększa javaMaxHeapSize.
    4. Ustaw lokalizację dodatkowych bibliotek.
    5. Dodaj do pakietu SDK do nawigacji te wartości: repositories i dependencies.
    6. Zastąp numery wersji w zależnościach najnowszymi dostępnymi wersjami.

    Opcjonalne ustawienia skracające czas kompilacji

    • Włącz zmniejszanie kodu i zasobów za pomocą R8 lub ProGuard, aby usunąć nieużywany kod i zasoby z zależności. Jeśli etap R8/ProGuard zajmuje zbyt dużo czasu, rozważ włączenie multidexu na potrzeby prac programistycznych.
    • Zmniejsz liczbę tłumaczeń językowych uwzględnionych w kompilacji: podczas tworzenia ustaw opcję resConfigs dla jednego języka. W przypadku wersji końcowej ustaw resConfigs dla języków, których używasz. Domyślnie Gradle zawiera ciągi tekstowe zasobów we wszystkich językach obsługiwanych przez pakiet SDK nawigacji.

    Dodanie decukiernienia na potrzeby obsługi Javy 8

    • Jeśli kompilujesz aplikację za pomocą wtyczki Android Gradle w wersji 4.0.0 lub nowszej, wtyczka rozszerza obsługę wielu interfejsów API języka Java 8. Więcej informacji znajdziesz w dokumentacji dotyczącej obsługi dezasugaringu w Java 8. Poniżej znajdziesz przykładowy fragment skryptu kompilacji, który pokazuje, jak skompilować i ustawić opcje zależności.
    • Zalecamy korzystanie z Gradle w wersji 8.4, wtyczki Androida do obsługi Gradle w wersji 8.3.0 oraz biblioteki Desugarcom.android.tools:desugar_jdk_libs_nio:2.0.3. Ta konfiguracja jest zgodna z pakietem SDK nawigacji na Androida w wersji 6.0.0 lub nowszej.
    • Biblioteka Desugar musi być włączona w przypadku modułu app i każdego modułu, który bezpośrednio zależy od pakietu SDK Nawigacji.

Poniżej znajdziesz przykład skryptu Gradle do kompilacji aplikacji. Sprawdź próbne aplikacje, aby dowiedzieć się, czy zestawy zależności zostały zaktualizowane, ponieważ wersja pakietu SDK Navigation, której używasz, może być nieco nowsza lub starsza niż ta opisana w dokumentacji.

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

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji opisujemy, jak przechowywać klucz interfejsu API, aby Twoja aplikacja mogła bezpiecznie się do niego odwoływać. Nie należy go dodawać do systemu kontroli wersji, dlatego zalecamy przechowywanie go w pliku secrets.properties, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku secrets.properties znajdziesz w artykule Pliki właściwości Gradle.

Aby usprawnić to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych na Androida.

Aby zainstalować wtyczkę Gradle obiektów tajnych na Androida w projekcie Mapy Google:

  1. W Android Studio otwórz najwyższy poziom pliku build.gradle.kts lub build.gradle i dodaj pod elementem buildscript kod:dependencies

    Kotlin

    buildscript {
    dependencies {
        classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
    }
}

    Zakręcony

    buildscript {
    dependencies {
        classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
    }
}
  2. Otwórz plik build.gradle.kts lub build.gradle na poziomie modułu i dodaj do elementu plugins ten kod:

    Kotlin

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

    Zakręcony

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. W pliku build.gradle.kts lub build.gradle na poziomie modułu sprawdź, czy wartości targetSdk i compileSdk są ustawione na 34.
  4. Zapisz plik i zsynchronizuj projekt z Gradle.
  5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a potem dodaj ten kod: Zastąp YOUR_API_KEY swoim kluczem API. Przechowuj klucz w tym pliku, ponieważ secrets.properties nie jest uwzględniany w systemie kontroli wersji. 
    NAV_API_KEY=YOUR_API_KEY
  6. Zapisz plik.

  7. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, czyli w tym samym folderze co plik secrets.properties, a potem dodaj podany niżej kod.

    NAV_API_KEY=DEFAULT_API_KEY

    Ten plik stanowi kopię zapasową klucza interfejsu API na wypadek, gdyby nie udało się znaleźć plikusecrets.properties, dzięki czemu kompilacje nie będą się załamywać. Może się tak zdarzyć, jeśli skopiujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties, a na komputerze lokalnym nie masz jeszcze utworzonego pliku secrets.properties, aby podać klucz interfejsu API.

  8. Zapisz plik.
  9. W pliku AndroidManifest.xml otwórz com.google.android.geo.API_KEY i zaktualizuj android:value attribute. Jeśli tag <meta-data> nie istnieje, utwórz go jako element podrzędny tagu <application>. 
    <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

    Uwaga: com.google.android.geo.API_KEY to zalecane nazwa metadanych klucza interfejsu API. Klucza o tej nazwie można używać do uwierzytelniania w kilku interfejsach API opartych na Mapach Google na platformie Android, w tym w pakiecie SDK Nawigacji na Androida. Ze względu na zgodność wsteczną interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ten starszy identyfikator umożliwia uwierzytelnianie tylko w ramach interfejsu Mapy Google na Androida w wersji 2. Aplikacja może podać tylko jedną z nazwy metadanych klucza interfejsu API. Jeśli podasz obie wartości, interfejs API zwróci wyjątek.

  10. W Android Studio otwórz plik build.gradle.kts lub build.gradle na poziomie modułu i edytuj właściwość secrets. Jeśli właściwość secrets nie istnieje, dodaj ją.

    Zmień właściwości wtyczki, aby ustawić wartość propertiesFileName na secrets.properties, wartość defaultPropertiesFileName na local.defaults.properties i ustawić inne właściwości.

    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"

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

    Zakręcony

    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"

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

Dodaj wymagane informacje w aplikacji

Jeśli w swojej aplikacji używasz pakietu SDK nawigacji na Androida, w sekcji powiadomień prawnych aplikacji musisz uwzględnić tekst atrybucji i licencja na oprogramowanie open source.

Wymagany tekst atrybucji i licencji open source znajdziesz w pliku ZIP pakietu SDK nawigacji na Androida:

  • NOTICE.txt
  • LICENSES.txt

Jeśli jesteś klientem Mobility lub Fleet Engine Deliveries

Jeśli korzystasz z usług Mobility lub Fleet Engine Deliveries, dowiedz się więcej o płatnościach z dokumentacji Mobility. Więcej informacji o rejestrowaniu transakcji znajdziesz w artykułach Konfigurowanie płatności, Rejestrowanie transakcji podlegających rozliczeniu, Raportowanie i Rejestrowanie transakcji podlegających rozliczeniu (Android).