Ta strona została przetłumaczona przez Cloud Translation API.

Konfigurowanie projektu na Androida Studio

Na tej stronie opisujemy, jak skonfigurować projekt Android Studio, aby używać pakietu Maps SDK na Androida bez korzystania z szablonu Map Google, który jest opisany w szybkim wprowadzeniu.

Szablon Map Google automatycznie konfiguruje i dodaje podstawową mapę do nowego projektu Android Studio. Możesz jednak dodać mapę do projektu na Androida, który korzysta z innego szablonu Androida Studio. Aby to zrobić, musisz ręcznie skonfigurować projekt, a następnie dodać mapę.

Krok 1. Konfigurowanie Androida Studio

W tym dokumencie opisujemy środowisko programistyczne korzystające z Androida Studio Hedgehog i wtyczki Androida do Gradle w wersji 8.2.

Krok 2. Konfigurowanie pakietu SDK

Biblioteka Maps SDK na Androida jest dostępna w repozytorium Google Maven. Aby dodać pakiet SDK do aplikacji:

W pliku settings.gradle.kts najwyższego poziomu dodaj portal wtyczek Gradle, repozytorium Google Maven i centralne repozytorium Maven w bloku pluginManagement. Blok pluginManagement musi występować przed wszystkimi innymi instrukcjami w skrypcie.
```
pluginManagement {
    repositories {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
} 
```

W pliku settings.gradle.kts najwyższego poziomu dodaj repozytorium Maven firmy Google i centralne repozytorium Maven w bloku dependencyResolutionManagement:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

W pliku build.gradle.kts lub build.gradle na poziomie modułu dodaj zależność Usług Google Play dla pakietu Maps SDK na Androida.

Kotlin

dependencies {

    // Maps SDK for Android
    implementation("com.google.android.gms:play-services-maps:19.0.0")
}

Zakręcony

dependencies {

    // Maps SDK for Android
    implementation "com.google.android.gms:play-services-maps:19.0.0"
}

W pliku build.gradle.kts lub build.gradle na poziomie modułu ustaw wartości compileSdk i minSdk w ten sposób:

Uwaga: upewnij się, że wartość compileSdk wynosi co najmniej 34, a wartość minSdk – co najmniej 21.

Kotlin

android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}

Zakręcony

android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        // ...
    }
}

W sekcji buildFeatures pliku build.gradle.kts lub build.gradle na poziomie modułu dodaj klasę BuildConfig, której możesz użyć do uzyskiwania dostępu do wartości metadanych zdefiniowanych w dalszej części tej procedury:
Kotlin
```
android {
  // ...
  buildFeatures {
    buildConfig = true
    // ...
  }
}
```
Zakręcony
```
android {
  // ...
  buildFeatures {
    buildConfig true
    // ...
  }
}
```

Krok 3. Dodaj klucz interfejsu API do projektu

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:

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

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

W pliku build.gradle.kts lub build.gradle na poziomie modułu upewnij się, że wartości targetSdk i compileSdk to 34.
Zsynchronizuj projekt z Gradle.
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.
Uwaga: jeśli plik secrets.properties nie istnieje, utwórz go w tym samym folderze co plik local.properties.
```
MAPS_API_KEY=YOUR_API_KEY
```
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.

Uwaga: wpisz kod w takiej formie, w jakiej się wyświetla. Nie zastępuj DEFAULT_API_KEY kluczem interfejsu API.
```
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>
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 Maps 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.

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

Krok 4. Zaktualizuj plik manifestu aplikacji

W tej sekcji opisujemy ustawienia, które należy dodać do pliku AndroidManifest.xml.

Numer wersji Usług Google Play

Dodaj tę deklarację w elemencie application. Spowoduje to osadzenie wersji Usług Google Play, z którą skompilowano aplikację.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version" />

Dostęp do lokalizacji

Jeśli Twoja aplikacja potrzebuje dostępu do lokalizacji użytkownika, musisz poprosić o uprawnienia do lokalizacji w pliku AndroidManifest.xml. Dostępne są opcje ACCESS_FINE_LOCATION, która podaje dokładną lokalizację urządzenia, oraz ACCESS_COARSE_LOCATION, która jest mniej precyzyjna. Więcej informacji znajdziesz w przewodniku dotyczącym danych o lokalizacji.

Aby poprosić o uprawnienie ACCESS_FINE_LOCATION, dodaj ten kod do elementu manifest:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Uprawnienia dostępu do pamięci zewnętrznej

Jeśli kierujesz reklamy na wersję 8.3 lub nowszą pakietu SDK usług Google Play, nie potrzebujesz uprawnienia WRITE_EXTERNAL_STORAGE. Jeśli kierujesz reklamy na starsze wersje pakietu SDK usług Google Play, musisz poprosić o uprawnienie WRITE_EXTERNAL_STORAGE w elemencie manifest.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Starsza biblioteka Apache HTTP

Jeśli używasz wersji com.google.android.gms:play-services-maps:16.0.0 lub starszej, a aplikacja jest kierowana na interfejs API na poziomie 28 (Android 9.0) lub wyższym, musisz umieścić w elemencie <application> pliku AndroidManifest.xml następującą deklarację: W przeciwnym razie pomiń to oświadczenie.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false" />

Krok 5. Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację korzystającą z pakietu SDK Map Google na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub emulatorze Androida z Androidem 5.0 lub nowszym, który zawiera interfejsy API Google.

Aby używać urządzenia z Androidem, postępuj zgodnie z instrukcjami w artykule Uruchamianie aplikacji na urządzeniu.
Aby używać emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować emulator za pomocą menedżera urządzenia wirtualnego z Androidem (AVD), który jest częścią Android Studio.
Uwaga: jeśli zdecydujesz się użyć emulatora Androida, wybierz urządzenie z ikoną Play wyświetlaną w kolumnie Sklep Play. Ta ikona oznacza, że te profile są w pełni zgodne z CTS i mogą używać obrazów systemu, które zawierają aplikację Sklep Play:

Krok 6. Opcjonalnie sprawdź, czy Usługi Play są obsługiwane

Pakiet Maps SDK na Androida wymaga, aby na urządzeniu, na którym wdrażasz aplikację, były zainstalowane Usługi Google Play. Google udostępnia metodę, którą możesz wywołać z aplikacji, aby to sprawdzić. Więcej informacji znajdziesz w artykule Sprawdzanie, czy Usługi Google Play są zainstalowane.

Dalsze kroki

Po skonfigurowaniu projektu możesz dodać mapę.

Konfigurowanie projektu na Androida Studio Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Krok 1. Konfigurowanie Androida Studio

Krok 2. Konfigurowanie pakietu SDK

Kotlin

Zakręcony

Kotlin

Zakręcony

Kotlin

Zakręcony

Krok 3. Dodaj klucz interfejsu API do projektu

Kotlin

Zakręcony

Kotlin

Zakręcony

Kotlin

Zakręcony

Krok 4. Zaktualizuj plik manifestu aplikacji

Numer wersji Usług Google Play

Dostęp do lokalizacji

Uprawnienia dostępu do pamięci zewnętrznej

Starsza biblioteka Apache HTTP

Krok 5. Konfigurowanie urządzenia z Androidem

Krok 6. Opcjonalnie sprawdź, czy Usługi Play są obsługiwane

Dalsze kroki

Konfigurowanie projektu na Androida Studio