Krótkie wprowadzenie do Maps SDK na Androida

Utwórz aplikację na Androida, która wyświetla mapę, korzystając z szablonu widoków Map Google w Android Studio. Jeśli masz już projekt w Android Studio, który chcesz skonfigurować, zapoznaj się z artykułem Konfigurowanie projektu w Android Studio.

Uwaga: w tym krótkim wprowadzeniu używamy szablonu Google Maps Views Activity, który tworzy układ XML z elementem SupportMapFragment. Jeśli tworzysz interfejs za pomocą Jetpack Compose, zapoznaj się z biblioteką Maps Compose.

Ten krótki przewodnik jest przeznaczony dla programistów aplikacji na Androida, którzy znają podstawy tworzenia aplikacji na Androida w języku Kotlin lub Java.

Informacje o środowisku programistycznym

Zalecamy korzystanie z najnowszej stabilnej wersji Android Studio i wtyczki Androida do obsługi Gradle.

Uwaga: jeśli Twoje środowisko programistyczne używa innej wersji Androida Studio lub Gradle, może być konieczne zmodyfikowanie kroków w zależności od środowiska. Więcej informacji o wersjach Android Studio i Gradle znajdziesz w artykule Zgodność wtyczki Androida do obsługi Gradle i Android Studio.

Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację, która korzysta z pakietu Maps SDK na Androida, musisz ją wdrożyć na urządzeniu z Androidem lub w emulatorze Androida z systemem Android 6.0 lub nowszym i interfejsami API Google.

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

  

  Okno Dodaj urządzenie w Menedżerze urządzeń Android Studio, w którym widać profile urządzeń wirtualnych z ikoną Google Play w kolumnie Play.

Tworzenie projektu Map Google w Android Studio

1. Otwórz Android Studio i w oknie Welcome to Android Studio (Witamy w Android Studio) kliknij New Project (Nowy projekt).

2. W oknie New Project (Nowy projekt) w kategorii Phone and Tablet (Telefon i tablet) wybierz No Activity (Brak aktywności), a następnie kliknij Next (Dalej).

   Uwaga: jeśli zaczniesz od domyślnego szablonu Pusta aktywność (Jetpack Compose) zamiast Brak aktywności, a później dodasz Aktywność widoków Map Google, aplikacja MapsActivity (AppCompatActivity) ulegnie awarii przy uruchamianiu z błędem IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity, ponieważ szablon Compose ustawia element nadrzędny motywu w res/values/themes.xml na android:Theme.Material.Light.NoActionBar. Aby uniknąć tej awarii, zaktualizuj parent motywu w res/values/themes.xml do Theme.AppCompat.DayNight.NoActionBar i upewnij się, że .MapsActivity jest skonfigurowany jako aktywność MAIN/LAUNCHER w AndroidManifest.xml.

3. Wypełnij formularz Nowy projekt:

   • Ustaw Language (Język) na Java lub Kotlin. Oba języki są w pełni obsługiwane przez pakiet Maps SDK na Androida. Więcej informacji o języku Kotlin znajdziesz w artykule Tworzenie aplikacji na Androida w języku Kotlin.

   • W polu Minimalna wersja pakietu SDK ustaw wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję wyższą niż minimalna wersja wymagana przez pakiet Maps SDK na Androida w wersji 20.0.x, czyli interfejs API Androida na poziomie 23 („Marshmallow”; Android 6.0) lub wyższym. Najnowsze informacje o wymaganiach dotyczących wersji pakietu SDK znajdziesz w informacjach o wersji.

     Uwaga: jeśli nie masz pewności, którą wersję pakietu SDK wybrać, kliknij link Pomóż mi wybrać, aby wyświetlić informacje o dystrybucji obsługiwanych pakietów Android SDK. Jeśli na przykład wybierzesz Android API Level 23 („Marshmallow”; Android 6.0), aplikacja powinna działać na ponad 99% urządzeń z Androidem.

   • Ustaw język konfiguracji kompilacji na Kotlin DSL lub Groovy DSL. Fragmenty kodu dla obu języków konfiguracji kompilacji są pokazane w poniższych procedurach.

4. Kliknij Zakończ.

   Android Studio uruchomi Gradle i utworzy projekt. Może to chwilę potrwać.

5. Dodaj aktywność związaną z wyświetleniami w Mapach Google:

   1. Kliknij prawym przyciskiem folder app w projekcie.

   2. Wybierz Nowy > Google > Aktywność związana z wyświetleniami w Mapach Google:

      

      Dodawanie aktywności widoków Map Google z menu kontekstowego app w Android Studio.

   3. W oknie Nowa aktywność na Androidzie zaznacz pole wyboru Aktywność w programie uruchamiającym.

   4. Kliknij Zakończ.

      Więcej informacji znajdziesz w artykule Dodawanie kodu z szablonu.

6. Po zakończeniu kompilacji Android Studio otworzy pliki AndroidManifest.xml i MapsActivity. Aktywność może mieć inną nazwę w zależności od tego, co zostało skonfigurowane podczas konfiguracji.

   Uwaga: projekt wygenerowany przez szablon Aktywność związana z wyświetleniami Map Google nie będzie działać bez dodatkowej konfiguracji. Chociaż szablon dodaje wtyczkę Gradle obiektów tajnych dla Androida do plików libs.versions.toml i build.gradle.kts, nie konfiguruje pliku secrets.properties, lecz umieszcza obiekt zastępczy YOUR_API_KEY bezpośrednio w pliku AndroidManifest.xml (ze starszymi komentarzami odwołującymi się do pliku local.properties). Nie wklejaj klucza interfejsu API bezpośrednio do pliku AndroidManifest.xml ani nie dodawaj go do pliku local.properties. Zamiast tego postępuj zgodnie z instrukcjami podanymi w sekcjach Konfigurowanie projektu Google Cloud i Dodawanie klucza interfejsu API do aplikacji, aby zapisać MAPS_API_KEY w pliku secrets.properties, skonfigurować blok secrets w pliku Gradle na poziomie modułu i ustawić android:value="${MAPS_API_KEY}" w AndroidManifest.xml.

Konfigurowanie projektu Google Cloud

Wykonaj wymagane czynności konfiguracyjne w konsoli Cloud, klikając te karty:

Krok 1

Konsola

1. W konsoli Google Cloud na stronie selektora projektów kliknij Utwórz projekt, aby rozpocząć tworzenie nowego projektu Cloud.

   Otwórz stronę selektora projektów

2. Sprawdź, czy w projekcie Cloud włączone są płatności. Sprawdź, czy w projekcie są włączone płatności.

   Google Cloud oferuje bezpłatny okres próbny. Okres próbny kończy się po upływie 90 dni lub po naliczeniu na koncie opłat w wysokości 300 USD (w zależności od tego, co nastąpi wcześniej). Możesz zrezygnować w każdej chwili. Więcej informacji znajdziesz w artykułach o środkach na koncie rozliczeniowym i rozliczeniach.

Pakiet SDK Cloud

gcloud projects create "PROJECT"

Więcej informacji o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i tych poleceniach:

• gcloud projects create

Uwaga: jeśli zasoby utworzone podczas wykonywania ćwiczenia nie będą Ci później potrzebne, nie wybieraj istniejącego projektu, tylko utwórz nowy. Po jej zakończeniu możesz usunąć projekt wraz ze wszystkimi zasobami, które są z nim powiązane.

Krok 2

Aby korzystać z Google Maps Platform, musisz włączyć interfejsy API lub pakiety SDK, których chcesz używać w projekcie.

Konsola

Włączanie pakietu Maps SDK na Androida

Pakiet SDK Cloud

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

Więcej informacji o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i tych poleceniach:

• gcloud services enable
• gcloud services disable

Krok 3

Ten krok dotyczy tylko procesu tworzenia klucza interfejsu API. Jeśli używasz klucza interfejsu API w środowisku produkcyjnym, zdecydowanie zalecamy jego ograniczenie. Więcej informacji znajdziesz na stronie Korzystanie z kluczy interfejsu API dotyczącej konkretnej usługi.

Klucz interfejsu API to unikalny identyfikator używany do uwierzytelniania żądań powiązanych z projektem na potrzeby wykorzystania i płatności. Z projektem musi być powiązany co najmniej 1 klucz interfejsu API.

Aby utworzyć klucz interfejsu API:

Konsola

1. Otwórz stronę Google Maps Platform > Dane logowania.

   Otwórz stronę Dane logowania

2. Na stronie Dane logowania kliknij Utwórz dane logowania > Klucz interfejsu API.
   W oknie Utworzono klucz interfejsu API pojawi się nowo utworzony klucz interfejsu API.
3. Kliknij Zamknij.
   Nowy klucz interfejsu API pojawi się na stronie Dane logowania w sekcji Klucze interfejsu API.
   (Pamiętaj, aby ograniczyć klucz interfejsu API przed użyciem go w środowisku produkcyjnym).

Pakiet SDK Cloud

gcloud services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

Więcej informacji o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i tych poleceniach:

• gcloud services api-keys create

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

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.

   Uwaga: wpisz kod w wyświetlonej postaci. Nie zastępuj DEFAULT_API_KEY kluczem interfejsu API.

   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. W pliku AndroidManifest.xml przejdź do com.google.android.geo.API_KEY i zaktualizuj atrybut android:value w ten sposób:

   <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 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 API Map Google dla 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.

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

Uwaga: jeśli Logcat zgłasza błąd E/Google Maps Android API: Authorization failure lub nie udaje się wczytać kafelków mapy, sprawdź, czy w projekcie Google Cloud jest włączony Maps SDK for Android, czy klucz interfejsu API w scalonej aplikacji AndroidManifest.xml jest prawidłowy oraz czy w przypadku, gdy klucz interfejsu API korzysta z ograniczeń aplikacji na Androida, nazwa pakietu projektu (np. com.example.myfirstmapsapp) i odcisk cyfrowy SHA-1 magazynu kluczy podpisywania (np. ~/.android/debug.keystore) są dodane do dozwolonych aplikacji na Androida w Google Cloud.

Sprawdź kod

Przeanalizuj kod dostarczony przez szablon. W szczególności zwróć uwagę na te pliki w projekcie Android Studio.

Plik aktywności w Mapach

Plik aktywności w Mapach to główna aktywność aplikacji, która zawiera kod do zarządzania mapą i jej wyświetlania. Domyślnie plik, który definiuje aktywność, ma nazwę MapsActivity.java, a jeśli jako język aplikacji ustawisz Kotlin, MapsActivity.kt.

Główne elementy aktywności w Mapach:

• Obiekt SupportMapFragment zarządza cyklem życia mapy i jest elementem nadrzędnym interfejsu aplikacji.

• Obiekt GoogleMap zapewnia dostęp do danych i widoku mapy. Jest to główna klasa pakietu Maps SDK na Androida. W przewodniku Obiekty mapy znajdziesz bardziej szczegółowe informacje o obiektach SupportMapFragment i GoogleMap.

• Funkcja moveCamera wyśrodkowuje mapę na współrzędnych LatLng dla Sydney w Australii. Pierwsze ustawienia, które należy skonfigurować podczas dodawania mapy, to zwykle lokalizacja mapy i ustawienia kamery, takie jak kąt widzenia, orientacja mapy i poziom powiększenia. Szczegółowe informacje znajdziesz w przewodniku Kamera i widok.

• Funkcja addMarker dodaje znacznik do współrzędnych Sydney. Szczegółowe informacje znajdziesz w przewodniku po znacznikach.

Kotlin

// Add a marker in Sydney and move the camera
val sydney = LatLng(-34.0, 151.0)
map.addMarker(
    MarkerOptions()
        .position(sydney)
        .title("Marker in Sydney"),
)
map.moveCamera(CameraUpdateFactory.newLatLng(sydney))

      

Java

// Add a marker in Sydney and move the camera
LatLng sydney = new LatLng(-34, 151);
map.addMarker(new MarkerOptions().position(sydney).title("Marker in Sydney"));
map.moveCamera(CameraUpdateFactory.newLatLng(sydney));

      

Plik Gradle modułu

Plik build.gradle.kts lub build.gradle na poziomie modułu zawiera tę zależność Map, która jest wymagana przez pakiet Maps SDK na Androida.

Kotlin

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

Zakręcony

dependencies {

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

Jeśli Twój projekt korzysta z katalogu wersji Gradle (gradle/libs.versions.toml), zdefiniuj zależność play-services-maps w pliku libs.versions.toml:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

Uwaga: dokładna wersja może się zmieniać w zależności od bieżącej wersji pakietu Maps SDK na Androida.

Więcej informacji o zarządzaniu zależnością Map znajdziesz w artykule o obsłudze wersji.

Plik układu XML

Plik activity_maps.xml to plik układu XML, który definiuje strukturę interfejsu aplikacji. Plik znajduje się w katalogu res/layout. Plik activity_maps.xml deklaruje fragment, który zawiera te elementy:

• tools:context ustawia domyślną aktywność fragmentu na MapsActivity, która jest zdefiniowana w pliku aktywności w Mapach.
• android:name ustawia nazwę klasy fragmentu na SupportMapFragment, czyli typ fragmentu używany w pliku aktywności w Mapach.

Plik układu XML zawiera ten kod:

<fragment xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:map="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/map"
    android:name="com.google.android.gms.maps.SupportMapFragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context=".MapsActivity" />

Wdrażanie i uruchamianie aplikacji

Po pomyślnym uruchomieniu aplikacji wyświetli się mapa wyśrodkowana na Sydney w Australii ze znacznikiem na mieście, jak pokazano na zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

1. W Android Studio kliknij opcję menu Uruchom (lub ikonę przycisku odtwarzania), aby uruchomić aplikację.
2. Gdy pojawi się prośba o wybranie urządzenia, wybierz jedną z tych opcji:
   • Wybierz urządzenie z Androidem połączone z komputerem.
   • Możesz też kliknąć przycisk opcji Uruchom emulator i wybrać skonfigurowane urządzenie wirtualne.
3. Kliknij OK. Android Studio uruchomi Gradle, aby utworzyć aplikację, a następnie wyświetli wyniki na urządzeniu lub w emulatorze. Uruchomienie aplikacji może potrwać kilka minut.

Dalsze kroki

• Konfigurowanie mapy: ten dokument opisuje, jak skonfigurować początkowe i bieżące ustawienia mapy, takie jak pozycja kamery, typ mapy, komponenty interfejsu i gesty.

• Dodawanie mapy do aplikacji na Androida (Kotlin): to ćwiczenie przeprowadzi Cię przez aplikację, która demonstruje niektóre dodatkowe funkcje pakietu Maps SDK na Androida.

• Używanie biblioteki Maps Android KTX: ta biblioteka rozszerzeń Kotlin (KTX) umożliwia korzystanie z kilku funkcji języka Kotlin podczas używania pakietu Maps SDK na Androida.