Konfigurowanie projektu w Android Studio

Na tej stronie znajdziesz informacje o integrowaniu pakietu SDK na potrzeby 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.

Uwaga: ta metoda jest niezgodna z niektórymi bibliotekami, które są zależne od pakietu SDK nawigacji przez poprzedni identyfikator artefaktu. Dotyczy to też pakietu Driver SDK w wersji 4.4 lub starszej.

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

   Uwaga: jeśli jesteś klientem korzystającym z Usług przenośnych, który przechodzi na nowszą wersję z pierwotnego prywatnego repozytorium Maven, pamiętaj, że nazwy grup i artefaktów uległy zmianie, a wtyczka com.google.cloud.artifactregistry.gradle-plugin nie jest już potrzebna.

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 build.gradle najwyższego poziomu:

   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 pom.xml:

   <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 pod kątem udanej kompilacji i użycia pakietu Navigation SDK.

Aktualizowanie właściwości lokalnych

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

Aktualizowanie właściwości Gradle

• W folderze skryptów Gradle Scripts otwórz plik gradle.properties i dodaj następujące elementy, jeśli jeszcze ich nie ma:

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

Aktualizowanie skryptu 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 Navigation SDK

  1. Ustaw minSdkVersion na 23 lub więcej.
  2. Ustaw wartość targetSdkVersion na 34 lub większą.
  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 pozwalające skrócić czas kompilacji

  • Włącz ograniczanie kodu i ograniczanie zasobów przy użyciu R8/ProGuard, aby usunąć nieużywany kod i zasoby z zależności. Jeśli wykonanie kroku R8/ProGuard trwa zbyt długo, rozważ włączenie multidex na potrzeby prac programistycznych.
  • Zmniejsz liczbę tłumaczeń na jeden język uwzględniony w kompilacji: ustaw resConfigs na 1 język podczas programowania. 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 artykule o obsłudze odsłuchiwania języka Java 8. Sposób kompilacji i zależności znajdziesz w poniższym przykładowym fragmencie skryptu kompilacji.
  • Zalecamy korzystanie z narzędzia Gradle w wersji 8.4, wtyczki Androida do obsługi Gradle w wersji 8.3.0 i biblioteki Desugar com.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 dowolnego modułu, który bezpośrednio zależy od pakietu SDK Navigation.

Poniżej znajdziesz przykład skryptu Gradle do kompilacji aplikacji. Sprawdź w przykładowych aplikacjach, czy dostępne są zaktualizowane zestawy zależności, ponieważ wersja pakietu Navigation SDK, której używasz, może być nieco późniejsza lub późniejsza niż ta dokumentacją.

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 zapisać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie należy sprawdzać klucza interfejsu API w systemie kontroli wersji, więc zalecamy zapisanie 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 korzystanie z wtyczki do Gradle obiektów tajnych na Androida.

Uwaga: najnowsze wymagania systemowe i instrukcje instalacji znajdziesz w dokumentacji wtyczki do Gradle obiektów tajnych do Androida dostępnej na GitHubie.

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

1. W Android Studio otwórz plik build.gradle.kts lub build.gradle najwyższego poziomu i dodaj poniższy kod do elementu dependencies w sekcji buildscript.

   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 poniższy kod do elementu plugins.

   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 targetSdk i compileSdk mają wartość 34.
4. Zapisz plik i zsynchronizuj projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj poniższy kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Przechowuj klucz w tym pliku, ponieważ secrets.properties nie jest uwzględniany w systemie kontroli wersji.
   Uwaga: jeśli plik secrets.properties nie istnieje, utwórz go w tym samym folderze co plik local.properties.

   NAV_API_KEY=YOUR_API_KEY

6. Zapisz plik.

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

   Uwaga: wpisz kod, który wyświetla się poniżej. Nie zastępuj DEFAULT_API_KEY swoim kluczem API.

   NAV_API_KEY=DEFAULT_API_KEY

   Ten plik zawiera kopię zapasową klucza interfejsu API na wypadek, gdyby plik secrets.properties nie został znaleziony. Pozwala to uniknąć błędu kompilacji. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija atrybut secrets.properties, i nie masz jeszcze lokalnego pliku secrets.properties umożliwiającego przekazanie klucza interfejsu API.

8. Zapisz plik.
9. W pliku AndroidManifest.xml przejdź do sekcji 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 zmień właściwość secrets. Jeśli właściwość secrets nie istnieje, dodaj ją.

    Zmień właściwości wtyczki, by ustawić propertiesFileName na secrets.properties, ustaw defaultPropertiesFileName na local.defaults.properties i ustaw pozostałe 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 o przypisaniu 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.

Ważne: aby uwzględnić informacje o autorze, dodaj je jako niezależną pozycję w menu lub pozycję w menu Informacje.

Wymagany tekst atrybucji i licencje open source znajdziesz w pliku ZIP pakietu Navigation SDK 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 rozliczeń, Rejestrowanie transakcji podlegających rozliczeniu, Raportowanie i Rejestrowanie transakcji podlegających rozliczeniu (Android).