Konfigurowanie projektu w Android Studio

Na tej stronie dowiesz się, jak zintegrować pakiet Navigation SDK z projektem programistycznym.

Dodawanie pakietu Navigation SDK do projektu

Pakiet Navigation SDK jest dostępny w repozytorium Google Maven. 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 poniższą zależność, zastępując obiekt zastępczy VERSION_NUMBER odpowiednią wersją pakietu Navigation SDK na Androida.

    Gradle

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

    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 zależności, które używają pakietu Maps SDK, musisz wykluczyć zależność w każdej zadeklarowanej zależności, która opiera się na pakiecie Maps SDK.

    Gradle

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

    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

    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 pomyślnie utworzyć i używać pakietu Navigation SDK.

Aktualizowanie właściwości lokalnych

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

Aktualizowanie skryptu kompilacji Gradle

  • Otwórz plik build.gradle (Module:app) i postępuj zgodnie z tymi wskazówkami, aby zaktualizować ustawienia zgodnie z wymaganiami pakietu Navigation SDK. Możesz też ustawić opcje optymalizacji.

    Wymagane ustawienia pakietu Navigation SDK

    1. Ustaw minSdkVersion na 24 lub więcej.
    2. Ustaw wartość targetSdkVersion na 36 lub wyższą.
    3. Dodaj ustawienie dexOptions, które zwiększa javaMaxHeapSize.
    4. Ustaw lokalizację dodatkowych bibliotek.
    5. Dodaj repositories i dependencies dla pakietu Navigation SDK.
    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/ProGuard, aby usunąć nieużywany kod i zasoby z zależności. Jeśli krok R8/ProGuard zajmuje zbyt dużo czasu, rozważ włączenie multidex na potrzeby prac programistycznych.
    • Zmniejsz liczbę tłumaczeń językowych uwzględnionych w kompilacji: podczas tworzenia aplikacji ustaw resConfigs dla jednego języka. W przypadku ostatecznej kompilacji ustaw resConfigs dla języków, których faktycznie używasz. Domyślnie Gradle zawiera ciągi zasobów we wszystkich językach obsługiwanych przez pakiet Navigation SDK.

    Dodawanie odlukrzania na potrzeby obsługi Javy 8

    • Jeśli tworzysz aplikację za pomocą wtyczki Androida do obsługi 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 artykule o obsłudze odlukrzania w Javie 8. Poniżej znajdziesz przykładowy fragment skryptu kompilacji, który pokazuje, jak skonfigurować opcje kompilacji i zależności.
    • Używaj wersji Gradle, wtyczki Androida do obsługi Gradle (AGP) i biblioteki Desugar, które odpowiadają wersji pakietu Navigation SDK. Zobacz tabelę poniżej.
    • Biblioteka Desugar musi być włączona w module app i każdym module, który bezpośrednio zależy od pakietu Navigation SDK.

W tabeli poniżej znajdziesz wersje bibliotek Gradle, AGP i Desugar wymagane w przypadku poszczególnych wersji pakietu Navigation SDK.

Wersja pakietu Navigation SDK Wersja Gradle Wersja AGP Biblioteka desugaryzacji
8.0.0 lub nowsza 9.1.0 9.0.1 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.7.0–7.9.0 8.13 8.13.2 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.3.0–7.6.0 8.11.1 8.10.0 com.android.tools:desugar_jdk_libs_nio:2.0.3

Poniżej znajdziesz przykładowy skrypt kompilacji Gradle dla aplikacji. Sprawdź przykładowe aplikacje, aby zobaczyć zaktualizowane zestawy zależności, ponieważ wersja pakietu Navigation SDK, 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.1.5'
}

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji opisano, jak przechowywać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie należy sprawdzać klucza interfejsu API w systemie kontroli wersji, dlatego zalecamy przechowywanie go w pliku secrets.properties w katalogu głównym projektu i wykluczenie tego pliku z kontroli wersji. Więcej informacji o plikach właściwości Gradle znajdziesz w artykule na ten temat.

Aby uprościć to zadanie, zalecamy użycie wtyczki Secrets Gradle do Androida.

Aby zainstalować wtyczkę Gradle obiektów tajnych dla Androida i zapisać klucz interfejsu API:

  1. W Android Studio otwórz plik build.gradle.kts lub build.gradle najwyższego poziomu i dodaj ten kod do bloku plugins.

    Kotlin

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

    Zakręcony

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. Otwórz plik build.gradle.kts lub build.gradle na poziomie modułu i dodaj ten kod do elementu plugins.

    Kotlin

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

    Zakręcony

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. Jeśli używasz Android Studio, zsynchronizuj projekt z Gradle.
  4. Otwórz plik secrets.properties w katalogu najwyższego poziomu i dodaj podany niżej kod. Zastąp YOUR_API_KEY kluczem interfejsu API. Dodaj secrets.properties do pliku .gitignore (lub w inny sposób wyklucz go z systemu kontroli wersji), aby nie sprawdzać klucza interfejsu API w systemie kontroli wersji. 
    MAPS_API_KEY=YOUR_API_KEY

  5. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, czyli w tym samym folderze, w którym znajduje się plik secrets.properties, a następnie dodaj podany niżej kod.

    MAPS_API_KEY=DEFAULT_API_KEY

    Ten plik służy do podania zapasowej lokalizacji klucza interfejsu API, jeśli nie można znaleźć pliku secrets.properties, aby kompilacje nie kończyły się niepowodzeniem. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties, i nie utworzysz jeszcze lokalnie pliku secrets.properties, aby podać klucz interfejsu API.

  6. Możesz dodać klucz interfejsu API do pliku AndroidManifest.xml lub podać go automatycznie.
    • Dodaj klucz interfejsu API do AndroidManifest.xml: 
      <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

      Uwaga: com.google.android.geo.API_KEY to zalecana nazwa metadanych klucza interfejsu API. Klucz o tej nazwie może służyć do uwierzytelniania w wielu interfejsach API opartych na Mapach Google na platformie Androida, w tym w pakiecie Navigation SDK na Androida. Ze względu na zgodność wsteczną interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ta starsza nazwa umożliwia uwierzytelnianie tylko w interfejsie API Map Google na Androida w wersji 2. Aplikacja może określić tylko jedną z nazw metadanych klucza interfejsu API. Jeśli podasz obie wartości, interfejs API zgłosi wyjątek.

    • Podaj klucz interfejsu API automatycznie:

      Wtyczka Gradle obiektów tajnych udostępnia klucz w klasie BuildConfig. W ramach inicjowania aplikacji (np. w metodzie Application.onCreate()) wywołaj metodę w ten sposób:

      Kotlin

      1. Dodaj te instrukcje importu: 
        import com.google.android.libraries.navigation.NavigationApi
      2. Dodaj do metody Application.onCreate() te wiersze: 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. Dodaj te instrukcje importu: 
        import com.google.android.libraries.navigation.NavigationApi;
      2. Dodaj do metody Application.onCreate() te wiersze: 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      Uwaga: podczas korzystania z setApiKey() pamiętaj o tych kwestiach:
      • Podaj klucz interfejsu API, który nie jest pusty ani nie ma wartości null.
      • Wywołaj setApiKey() tylko raz w okresie istnienia aplikacji. Jeśli metoda zostanie wywołana więcej niż raz, zgłosi błąd IllegalStateException.
      • Wywołaj setApiKey() przed zainicjowaniem innych komponentów pakietu Navigation SDK, takich jak Navigator.
      • Klucz podany w tej metodzie zastępuje wszystkie klucze interfejsu API w AndroidManifest.xml.
      • Używaj pakietu Navigation SDK w wersji 7.6 lub nowszej.

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

    Edytuj właściwości wtyczki, aby ustawić propertiesFileName na "secrets.properties", defaultPropertiesFileName na "local.defaults.properties" i skonfigurować 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 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"
}

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

Uwzględnianie wymaganych informacji o autorach w aplikacji

Jeśli w aplikacji używasz pakietu Navigation SDK na Androida, w sekcji informacji prawnych musisz umieścić informację o pochodzeniu danych i licencje open source.

Wymagane informacje o pochodzeniu danych i licencje open source znajdziesz w pliku ZIP pakietu SDK do nawigacji na Androida:

  • NOTICE.txt
  • LICENSES.txt

Jeśli jesteś klientem korzystającym z usługi Mobility lub Fleet Engine Deliveries

Jeśli jesteś klientem korzystającym z Mobility lub Fleet Engine Deliveries, dowiedz się więcej o rozliczeniach w 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).

Zależności ręczne (inne niż Gradle/Maven)

Jeśli Twój system kompilacji nie rozwiązuje zależności przechodnich (np. Bazel) lub jeśli integrujesz AAR ręcznie, musisz dodać te zależności do projektu. Gradle i Maven rozwiązują je automatycznie.

  • androidx.datastore:datastore-core
  • androidx.datastore:datastore-guava
  • com.google.guava:listenablefuture
  • androidx.concurrent:concurrent-futures