Krótkie wprowadzenie do Maps SDK na Androida

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

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

Informacje o środowisku programistycznym

To krótkie wprowadzenie zostało opracowane w Android Studio Hedgehog i z użyciem wtyczki Androida do obsługi Gradle w wersji 8.2.

Uwaga: jeśli w środowisku programistycznym używasz innej wersji Androida Studio lub Gradle, może być konieczne zmodyfikowanie tych kroków. Więcej informacji o wersjach Androida Studio i Gradle znajdziesz w artykule Zgodność wtyczki Androida do obsługi Gradle i Androida Studio.

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 opartym na Androidzie 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:

  

Tworzenie projektu Map Google w Android Studio

Procedura tworzenia projektu Map Google w Androidzie Studio została zmieniona w wersji Flamingo i nowszych.

1. Otwórz Android Studio i w oknie Witamy w Android Studio kliknij Nowy projekt.

2. W oknie Nowy projekt w kategorii Telefony i tablety wybierz Brak aktywności, a potem kliknij Dalej.

3. Wypełnij formularz Nowy projekt:

   • Ustaw 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 Kotlinie znajdziesz w artykule Tworzenie aplikacji na Androida w Kotlinie.

   • Ustaw Minimalną wersję SDK na wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję wyższą niż minimalna wymagana przez pakiet SDK Map Google na Androida w wersji 19.0.x, czyli poziom interfejsu API Androida 21 („Lollipop”; Android 5.0) lub wyższy. 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 SDK na Androida. Jeśli na przykład wybierzesz Android API Level 21 („Lollipop”; Android 5.0), Twoja 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ą przedstawione w procedurach poniżej.

4. Kliknij Zakończ.

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

5. Dodaj Aktywność w Widokach w Mapach Google:

   1. Kliknij prawym przyciskiem myszy folder app w projekcie.

   2. Kliknij Nowa > Google > Aktywność w widokach Map Google.

      

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

   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. Twoja aktywność może mieć inną nazwę, ale jest to nazwa skonfigurowana podczas instalacji.

   Uwaga: plik AndroidManifest.xml zawiera instrukcje dotyczące uzyskiwania klucza interfejsu Google Maps API i dodawania go do pliku local.properties. Nie dodawaj klucza interfejsu API do pliku local.properties. W ten sposób klucz interfejsu API jest przechowywany w mniej bezpieczny sposób. Zamiast tego postępuj zgodnie z instrukcjami w artykule Konfigurowanie projektu Google Cloud, aby utworzyć projekt Cloud i skonfigurować klucz interfejsu API.

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 włączone są płatności.

   Google Cloud oferuje okres próbny za 0,00 PLN. Okres próbny wygasa po 90 dniach lub po naliczeniu na koncie opłat o wartości 300 USD, w zależności od tego, co nastąpi wcześniej. Anuluj w dowolnym momencie. Więcej informacji znajdziesz w artykułach Środki na koncie rozliczeniowym i Rozliczenia i płatności.

Pakiet SDK Cloud

gcloud projects create "PROJECT"

Więcej informacji znajdziesz w artykułach Google Cloud SDK, Instalacja pakietu Cloud SDK oraz w opisach tych poleceń:

• 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 zakończeniu ćwiczenia 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 zamierzasz używać w projekcie.

Konsola

Włączanie pakietu SDK Map Google na Androida

Pakiet SDK Cloud

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

Więcej informacji znajdziesz w artykułach Google Cloud SDK, Instalacja pakietu Cloud SDK oraz w opisach tych poleceń:

• gcloud services enable
• gcloud services disable

Krok 3

Ten krok obejmuje tylko proces 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 API pojawi się nowo utworzony klucz.
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 znajdziesz w artykułach Google Cloud SDK, Instalacja pakietu Cloud SDK oraz w opisach tych poleceń:

• gcloud services api-keys create

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, 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 uprościć to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych na Androida.

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

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

   plugins {
       alias(libs.plugins.android.application) apply false
       alias(libs.plugins.jetbrains.kotlin.android) apply false
       alias(libs.plugins.kotlin.compose) apply false
       alias(libs.plugins.secrets.gradle.plugin) apply false
   }

   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 do elementu plugins ten kod:

   Kotlin

   plugins {
       // ...
       alias(libs.plugins.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 targetSdk i compileSdk to 34.
4. Zsynchronizuj projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu i 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

6. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, 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: sklonujesz aplikację z systemu kontroli wersji, który pomija secrets.properties, i nie utworzysz jeszcze lokalnie pliku secrets.properties, aby podać klucz interfejsu API.

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

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

Sprawdź kod

Sprawdź kod dostarczony przez szablon. W szczególności sprawdź 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 definiujący 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 mapy i widoku. Jest to główna klasa pakietu Maps SDK na Androida. W przewodniku Obiekty mapy znajdziesz więcej informacji o obiektach SupportMapFragment i GoogleMap.

• Funkcja moveCamera wyśrodkowuje mapę na współrzędnych LatLng 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 markerach.

Plik Gradle modułu

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

dependencies {

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

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

Więcej informacji o zarządzaniu zależnością Map znajdziesz w sekcji Obsługa 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 Map.
• android:name ustawia nazwę klasy fragmentu na SupportMapFragment, czyli typ fragmentu używany w pliku aktywności mapy.

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 miasta, jak widać na tym 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 podłączone do komputera.
   • Możesz też kliknąć opcję Uruchom emulator i wybrać skonfigurowane urządzenie wirtualne.
3. Kliknij OK. Android Studio uruchomi Gradle, aby skompilować aplikację, a następnie wyświetli wyniki na urządzeniu lub emulatorze. Uruchomienie aplikacji może potrwać kilka minut.

Dalsze kroki

• Konfigurowanie mapy: w tym dokumencie znajdziesz informacje o tym, jak skonfigurować ustawienia początkowe i ustawienia czasu działania mapy, takie jak pozycja kamery, typ mapy, komponenty interfejsu i gesty.

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

• Korzystanie z 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.