Konfigurowanie projektu – wersja 4.99 lub wcześniejsze

W tym przewodniku znajdziesz wymagania dotyczące konfiguracji kompilacji, które musisz spełnić, aby korzystać z pakietu Navigation SDK na Androida. W instrukcjach przyjęto, że masz zainstalowane środowisko IDE Androida i znasz się na programowaniu na Androida.

Minimalne wymagania dotyczące korzystania z pakietu Navigation SDK

Te wymagania dotyczą pakietu Navigation SDK na Androida w wersji 4.99 i starszych.

  • konsola Google Cloud;

    projekt z włączonym pakietem Navigation SDK. Aby uzyskać dostęp, skontaktuj się z przedstawicielem Google Maps Platform.

  • Aplikacja musi być kierowana na interfejs API na poziomie 30 lub wyższym.

  • Aby uruchomić aplikację utworzoną za pomocą pakietu Navigation SDK, na urządzeniu z Androidem muszą być zainstalowane i włączone Usługi Google Play.

  • Tekst dotyczący atrybucji i licencji musi zostać dodany do aplikacji.

Konfigurowanie projektów: projektu w konsoli Cloud i projektu Androida

Zanim utworzysz lub przetestujesz aplikację, musisz utworzyć projekt w konsoli Cloud i dodać dane logowania klucza interfejsu API. Aby uzyskać dostęp do pakietu Navigation SDK, projekt musi mieć udostępnianie. Wszystkie klucze w projekcie konsoli Cloud mają taki sam dostęp do pakietu Navigation SDK. Z kluczem może być powiązanych więcej niż 1 projekt deweloperski. Jeśli masz już projekt w konsoli, możesz dodać do niego klucz.

Konfigurowanie

  1. W ulubionej przeglądarce zaloguj się w konsoli Cloud i utwórz projekt konsoli Cloud.
  2. IDE, np. Android Studio, utwórz projekt aplikacji na Androida i zanotuj nazwę pakietu.
  3. Skontaktuj się z przedstawicielem Google Maps Platform, aby uzyskać dostęp do pakietu SDK Navigation w projekcie konsoli Cloud.
  4. Na panelu konsoli Cloud 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 deweloperskiego i odcisk cyfrowy SHA-1 tego klucza.
  7. Kliknij Zapisz.

Dodawanie pakietu Navigation SDK do projektu

Pakiet Navigation SDK jest dostępny w Maven lub jako pakiet AAR. Po utworzeniu projektu deweloperskiego możesz zintegrować z nim pakiet SDK, korzystając z jednego z tych podejść.

Używanie Mavena w przypadku pakietu SDK do nawigacji w wersji 4.5 i nowszych (zalecane)

Poniższy przykład korzysta z google() repozytorium Maven, które jest najprostszym i zalecanym sposobem dodawania pakietu Navigation SDK do projektu.

  1. Dodaj do konfiguracji Gradle lub Maven podaną niżej zależność, zastępując symbol zastępczy VERSION_NUMBER 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'
    }
    

    Jeśli uaktualniasz wersję z oryginalnego repozytorium Maven, pamiętaj, że nazwy grupy i artefaktu uległy zmianie, a wtyczka com.google.cloud.artifactregistry.gradle-plugin nie jest już potrzebna.

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

    Jeśli masz jakiekolwiek zależności, które korzystają z pakietu Maps SDK, musisz wykluczyć zależność w każdej zadeklarowanej zależności, która opiera się na pakiecie 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>
    

Używanie Mavena w przypadku pakietu Navigation SDK w wersji starszej niż 4.5 lub pakietu Driver SDK

Pakiet Navigation SDK jest nadal dostępny w oryginalnym repozytorium Maven w pozostałych wersjach 4. Jest to ta sama biblioteka ze wszystkimi aktualizacjami co wersja powyżej. Zapewnia zgodność z pakietem Driver SDK i innymi bibliotekami w okresie przejściowym. Korzystanie z tej zależności wymaga zalogowania się w projekcie w chmurze za pomocą polecenia gcloud podczas kompilacji.

  1. Skonfiguruj środowisko, aby uzyskać dostęp do repozytorium Maven Google, zgodnie z opisem w sekcji Wymagania wstępne dokumentacji pakietu Consumer SDK. Dostęp do pakietu Navigation SDK jest kontrolowany przez grupę obszaru roboczego.
  2. Dodaj do konfiguracji Gradle lub Maven podaną niżej zależność, zastępując symbol zastępczy VERSION_NUMBER wersją pakietu Navigation SDK.

    Gradle

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

    dependencies {
    ...
    implementation 'com.google.android.maps:navsdk:VERSION_NUMBER'
    }
    

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

    Jeśli masz jakiekolwiek zależności, które korzystają z pakietu Maps SDK, musisz wykluczyć zależność w każdej zadeklarowanej zależności, która opiera się na pakiecie 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>
    

Użyj pobranego pakietu AAR (niezalecane)

Pakiet Navigation SDK jest też dostępny jako pakiet AAR. Po utworzeniu projektu deweloperskiego możesz zintegrować pakiet SDK. W tych instrukcjach założono, że używasz środowiska IDE Android Studio.

  1. Pobierz najnowszą wersję pakietu Navigation SDK z udostępnionego Dysku Google i wyodrębnij ją. Jeśli nie masz dostępu, skontaktuj się z przedstawicielem.

  2. W Android Studio otwórz projekt i dodaj pakiet Usług Google Play za pomocą Menedżera SDK.

  3. W katalogu pliku ZIP skopiuj plik libs/google_navigation_navmap.aar do katalogu app/libs projektu.

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

    implementation(name: 'google_navigation_navmap', ext: 'aar')
    

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

Konfigurowanie kompilacji

Po utworzeniu projektu możesz skonfigurować ustawienia, aby umożliwić prawidłowe skompilowanie i używanie pakietu Navigation SDK.

Aktualizowanie lokalnych właściwości

  • 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 tymi wytycznymi, aby zaktualizować ustawienia zgodnie z wymaganiami pakietu Navigation SDK. Rozważ też ustawienie opcji optymalizacji.

    Wymagane ustawienia pakietu Navigation SDK

    1. Ustaw wartość minSdkVersion na 23 lub więcej.
    2. Ustaw wartość targetSdkVersion na co najmniej 30.
    3. Dodaj ustawienie dexOptions, które zwiększa javaMaxHeapSize.
    4. Ustaw lokalizację dodatkowych bibliotek.
    5. Dodaj symbole repositoriesdependencies 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 usuwać nieużywany kod i zasoby z zależności. Jeśli krok R8/ProGuard trwa zbyt długo, rozważ włączenie multidexu na potrzeby prac programistycznych.
    • Zmniejsz liczbę tłumaczeń językowych w kompilacji: podczas tworzenia aplikacji ustaw wartość resConfigs dla jednego języka. W przypadku ostatecznej wersji ustaw resConfigs dla języków, których faktycznie używasz. Domyślnie Gradle zawiera ciągi zasobów dla wszystkich języków obsługiwanych przez pakiet Navigation SDK.

Poniżej znajdziesz przykład skryptu kompilacji Gradle dla aplikacji. Sprawdź przykładowe aplikacje, aby poznać zaktualizowane zestawy zależności, ponieważ używana wersja pakietu Navigation SDK może być nieco nowsza lub starsza niż ta w dokumentacji.

apply plugin: 'com.android.application'
apply plugin: 'com.google.cloud.artifactregistry.gradle-plugin'

ext {
    androidxVersion = "1.0.0"
    lifecycle_version = "1.1.1"
}

android {
    compileSdkVersion 30
    buildToolsVersion '28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 30
        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 {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

// This tells Gradle where to look to find additional libraries - in this case, the
// google_navigation_navmap.aar file.
repositories {
    flatDir {
        dirs 'libs'
    }
    google()

    // Required for accessing the Navigation SDK on Google's Maven repository.
    maven {
        url "artifactregistry://us-west2-maven.pkg.dev/gmp-artifacts/transportation"
    }
}

dependencies {
    // Include the Google Navigation SDK
    implementation 'com.google.android.maps:navsdk:4.4.0'

    // The included AAR file under libs can be used instead of the Maven repository.
    // Uncomment the line below and comment out the previous dependency to use
    // the AAR file instead. Make sure that you add the AAR file to the libs directory.
    // implementation(name: 'google_navigation_navmap', ext: 'aar')

    // These dependencies are required for the Navigation SDK to function
    // properly at runtime.
    implementation 'org.chromium.net:cronet-fallback:69.3497.100'
    // Optional for Cronet users:
    // implementation 'org.chromium.net:cronet-api:69.3497.100'
    implementation 'androidx.appcompat:appcompat:${androidxVersion}'
    implementation 'androidx.cardview:cardview:${androidxVersion}'
    implementation 'com.google.android.material:material:${androidxVersion}'
    implementation 'androidx.mediarouter:mediarouter:${androidxVersion}'
    implementation 'androidx.preference:preference:${androidxVersion}'
    implementation 'androidx.recyclerview:recyclerview:${androidxVersion}'
    implementation 'androidx.legacy:legacy-support-v4:${androidxVersion}'
    implementation 'com.github.bumptech.glide:glide:4.9.0'
    implementation 'com.github.bumptech.glide:okhttp-integration:4.9.0'
    implementation 'android.arch.lifecycle:common-java8:$lifecycle_version'
    implementation 'com.android.support:multidex:1.0.3'
    implementation 'com.google.android.datatransport:transport-api:2.2.0'
    implementation 'com.google.android.datatransport:transport-backend-cct:2.2.0'
    implementation 'com.google.android.datatransport:transport-runtime:2.2.0'
    implementation 'joda-time:joda-time:2.9.9'
    annotationProcessor 'androidx.annotation:annotation:1.1.0'
    annotationProcessor 'com.github.bumptech.glide:compiler:4.9.0'
}

Dodawanie klucza interfejsu API do aplikacji

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

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

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

  1. W Android Studio otwórz plik najwyższego poziomu build.gradle.kts lub build.gradle i dodaj ten 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 ten 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 upewnij się, że wartości targetSdkcompileSdk to 34.
  4. Zsynchronizuj projekt z Gradle.
  5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj ten kod: Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Przechowuj klucz w tym pliku, ponieważ secrets.properties nie jest sprawdzany w systemie kontroli wersji.
    MAPS_API_KEY=YOUR_API_KEY
  6. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, czyli w tym samym folderze co plik secrets.properties, a następnie dodaj ten kod.

    MAPS_API_KEY=DEFAULT_API_KEY

    Ten plik służy jako lokalizacja kopii zapasowej klucza interfejsu API, jeśli nie można znaleźć pliku secrets.properties, aby kompilacje nie kończyły się niepowodzeniem. Może się to zdarzyć, jeśli:<ul><li>sklonujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties,</li><li>nie utworzysz jeszcze lokalnie pliku secrets.properties, aby podać klucz interfejsu API.</li></ul>

  7. 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 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 Android, 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 Android Maps API w wersji 2. Aplikacja może określić tylko jedną nazwę metadanych klucza interfejsu API. Jeśli określono oba te parametry, interfejs API zgłosi wyjątek.

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

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

Dodaj w aplikacji wymagane informacje o autorze

Jeśli w aplikacji używasz pakietu Navigation SDK na Androida, musisz umieścić tekst atrybucji i licencje open source w sekcji informacji prawnych aplikacji.

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

  • NOTICE.txt
  • LICENSES.txt