Konfigurowanie projektu

Ten przewodnik zawiera wymagania dotyczące konfiguracji kompilacji na potrzeby korzystania z pakietu Navigation SDK na Androida w wersji 5.0.0 lub nowszej.

W instrukcjach przyjęto, że masz zainstalowane IDE na Androida i znasz się na programowaniu na Androida.

Minimalne wymagania dotyczące korzystania z pakietu SDK nawigacji

Te wymagania dotyczą pakietu Navigation SDK na Androida w wersji 5.0.0 lub nowszej.

  • Projekt konsoli Google Cloud z włączonym pakietem Navigation SDK. Aby uzyskać pomoc, skontaktuj się z przedstawicielem Google Maps Platform.

  • Aplikacja musi mieć określone wersje Androida:

    • wersją docelową musi być Android 13 (poziom interfejsu API 33) lub nowszy.
    • minimalna wersja musi być na Androidzie 6 (poziom interfejsu API 23) lub nowszym.

  • Aby uruchomić aplikację stworzoną przy użyciu pakietu Navigation SDK, urządzenie z Androidem musi spełniać te wymagania:

    • zainstalowane i włączone usługi Google Play.

    • 2 GB lub więcej pamięci RAM.

    • Obsługa OpenGL ES 2.0. Zobacz dokumentację dotyczącą zgodności z Androidem 6.0 typu open source w przypadku 2D and 3D Graphics

  • Do aplikacji należy dodać informacje o atrybucji i licencjach.

Konfigurowanie projektów: projekt z konsoli Cloud i projekt na Androida

Zanim skompilujesz lub przetestujesz aplikację, musisz utworzyć projekt w konsoli Cloud i dodać dane logowania do klucza interfejsu API. Aby uzyskać dostęp do pakietu Navigation SDK, projekt musi mieć obsługę administracyjną. Wszystkie klucze w projekcie Cloud Console mają takie same uprawnienia dostępu do pakietu Navigation SDK. Z kluczem może być powiązany więcej niż 1 projekt programisty. Jeśli masz już projekt w konsoli, możesz dodać do niego klucz.

Aby skonfigurować:

  1. W ulubionej przeglądarce zaloguj się w konsoli Google Cloud i utwórz projekt w konsoli Cloud.
  2. W IDE, na przykład Android Studio, utwórz projekt tworzenia aplikacji na Androida i zanotuj nazwę pakietu.
  3. Aby uzyskać dostęp do pakietu Navigation SDK dla projektu w konsoli Cloud, skontaktuj się z przedstawicielem Google Maps Platform.
  4. W panelu Cloud Console w przeglądarce utwórz dane logowania, aby wygenerować klucz interfejsu API z ograniczeniami.
  5. Na stronie klucza interfejsu API w obszarze Ograniczenia aplikacji kliknij Aplikacje na Androida.
  6. Kliknij Dodaj nazwę pakietu i odcisk cyfrowy, a następnie wpisz nazwę pakietu projektu programistycznego i odcisk cyfrowy SHA-1 dla tego klucza.
  7. Kliknij Zapisz.

Dodawanie pakietu Navigation SDK do projektu

Pakiet Navigation SDK jest dostępny w aplikacji Maven. Po utworzeniu projektu programistycznego możesz zintegrować z nim pakiet SDK, korzystając z jednej z poniższych metod.

Poniższe polecenie korzysta z repozytorium Maven google(), które jest najprostszym i zalecanym sposobem dodania pakietu SDK nawigacji do projektu.

  1. Dodaj tę zależność do konfiguracji Gradle lub Maven, zastępując zmienną VERSION_NUMBER odpowiednią wersją pakietu Navigation SDK na Androida.

    Gradle

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

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

    W przypadku uaktualnienia z pierwotnego repozytorium Maven zauważysz, że nazwy grup i artefaktów uległy zmianie, a wtyczka com.google.cloud.artifactregistry.gradle-plugin nie jest już potrzebna.

    Do build.gradle najwyższego poziomu dodaj te elementy:

    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>com.google.android.libraries.navigation</groupId>
    <artifactId>navigation</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

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

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

Zaktualizuj właściwości lokalne

  • W folderze Gradle Scripts 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 poniższymi wskazówkami, aby zaktualizować ustawienia tak, aby spełniały wymagania pakietu Navigation SDK, i zastanów się nad ustawieniem opcji optymalizacji.

    Wymagane ustawienia pakietu Navigation SDK

    1. Ustaw minSdkVersion na 23 lub więcej.
    2. Ustaw targetSdkVersion na 33 lub więcej.
    3. Dodaj ustawienie dexOptions, które zwiększa wartość 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ąć z zależności nieużywany kod i zasoby. 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 ostatecznej kompilacji ustaw resConfigs dla języków, których używasz. Domyślnie Gradle zawiera ciągi zasobów dla wszystkich języków obsługiwanych przez pakiet Navigation SDK.

    Dodawanie decugaringu na potrzeby obsługi języka Java8

    • Jeśli tworzysz aplikację z użyciem wtyczki Androida do obsługi Gradle w wersji 4.0.0 lub nowszej, wtyczka rozszerza obsługę wielu interfejsów API w języku 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 fragmencie kodu kompilacji.

Poniżej znajduje się przykład skryptu kompilacji Gradle dla 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 33
        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:1.1.9'
}

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 o plikach właściwości Gradle.

Aby usprawnić to zadanie, zalecamy korzystanie z wtyczki do Gradle obiektów tajnych na Androida.

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

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

    Zakręcony

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

    Kotlin

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

    Zakręcony

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

    Kotlin

    plugins {
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}
  3. W pliku 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. Zapisz klucz w tym pliku, ponieważ secrets.properties nie jest sprawdzany w systemie kontroli wersji. 
    MAPS_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 następnie dodaj poniższy kod.

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

    Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Navigation SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

  10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

    Kotlin

    secrets {
    // Optionally specify a different file name containing your secrets.
    // The plugin defaults to "local.properties"
    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.*"
}

Umieść w aplikacji wymagane informacje o źródłach

Jeśli w swojej aplikacji używasz pakietu Navigation SDK na Androida, w sekcji Informacje prawne musisz uwzględnić tekst atrybucji i licencje open source.

Wymagany tekst atrybucji i licencje open source znajdziesz w pliku ZIP pakietu Navigation SDK na Androida:

  • NOTICE.txt
  • LICENSES.txt

Jeśli korzystasz z usługi Mobility lub Fleet Engine Deliveries

Jeśli korzystasz z usług Mobility lub Fleet Engine Deliveries, dowiedz się więcej o rozliczeniach, korzystając z dokumentacji dotyczącej mobilności. 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).