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 istniejący projekt Android Studio, który chcesz skonfigurować, zapoznaj się z artykułem Konfigurowanie projektu w Android 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

Ten krótki przewodnik został opracowany w Android Studio Hedgehog i wtyczce Gradle dla Androida w wersji 8.2.

Uwaga: jeśli środowisko programistyczne używa innej wersji Android Studio lub Gradle, konieczne może być zmodyfikowanie czynności w zależności od środowiska. Więcej informacji o wersjach Android Studio i Gradle znajdziesz w artykule Wtyczka Androida do obsługi Gradle i zgodność z Android 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 na emulatorze Androida opartym na Androidzie 5.0 lub nowszym, który zawiera interfejsy API Google.

• Aby korzystać z urządzenia z Androidem, wykonaj instrukcje opisane w artykule Uruchamianie aplikacji na urządzeniu z Androidem.
• Aby korzystać z 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. Ikona ta wskazuje, że te profile są w pełni zgodne z CTS i mogą używać obrazów systemowych, które obejmują aplikację Sklep Play:

  

Tworzenie projektu Map Google w Android Studio

Procedura tworzenia projektu Map Google w Android Studio została zmieniona w wersjach Flamingo i późniejszych.

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 SDK Map na Androida. Więcej informacji o Kotlinie znajdziesz w artykule Tworzenie aplikacji na Androida w Kotlinie.

   • Ustaw opcję Minimalny pakiet SDK na wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję nowszą niż minimalna wymagana przez pakiet SDK Map Google na Androida w wersji 19.0.x, która jest na poziomie interfejsu API 21 („Lollipop”, Android 5.0) lub wyższym. Najnowsze informacje o wymaganiach dotyczących wersji pakietu SDK znajdziesz w informacjach o wersji.

     Uwaga: jeśli nie wiesz, którą wersję pakietu SDK wybrać, kliknij link Pomóż mi wybrać, aby wyświetlić informacje o dystrybucji obsługiwanych pakietów SDK Androida. Jeśli na przykład wybierzesz poziom interfejsu API 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. W tych procedurach znajdziesz fragmenty kodu dla obu języków konfiguracji kompilacji.

4. Kliknij Zakończ.

   Android Studio uruchamia Gradle i kompiluje projekt. Może to chwilę potrwać.

5. Dodaj Aktywność związaną z wyświetleniem w Mapach Google:

   1. Kliknij prawym przyciskiem folder app w projekcie.

   2. Kliknij Nowe > Google > Aktywność wyświetleń w Mapach Google.

      

   3. W oknie Nowa aktywność na Androida zaznacz pole wyboru Aktywność w edytorze.

   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 ta, którą skonfigurowano podczas konfiguracji.

   Uwaga: plik AndroidManifest.xml zawiera instrukcje uzyskiwania klucza interfejsu API Map Google i dodawania go do pliku local.properties. Nie dodawaj klucza interfejsu API do pliku local.properties. W ten sposób klucz interfejsu API będzie mniej bezpieczny. Zamiast tego wykonaj instrukcje w artykule Konfigurowanie projektu Google Cloud, aby utworzyć projekt Cloud i skonfigurować klucz interfejsu API.

Konfigurowanie projektu Google Cloud

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

Krok 1

Konsola

1. W konsoli Google Cloud na stronie selektora projektu 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 Twoim projekcie są włączone płatności.

   Google Cloud oferuje bezpłatny okres próbny. Okres próbny wygasa po 90 dniach lub po przekroczeniu limitu płatności w wysokości 300 USD, zależnie od tego, co nastąpi wcześniej. Anuluj w każdej chwili. Google Maps Platform oferuje stałe 200 USD miesięcznie. Więcej informacji znajdziesz w artykułach Środki na koncie rozliczeniowym i Rozliczenia.

Pakiet SDK Cloud

gcloud projects create "PROJECT"

Dowiedz się więcej o pakiecie Google Cloud SDK, instalacji Cloud SDK i tych poleceniach:

• gcloud projects create

Uwaga: jeśli zasoby utworzone podczas ć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żyć w projekcie.

Konsola

Włączanie pakietu SDK Maps na Androida

Pakiet SDK Cloud

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

Dowiedz się więcej o pakiecie Google Cloud SDK, instalacji Cloud SDK i tych poleceniach:

• 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 ograniczenie tego klucza. Więcej informacji znajdziesz na stronie Korzystanie z kluczy API dotyczącej danej 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 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 wyświetli się nowo utworzony klucz API.
3. Kliknij Zamknij.
   Nowy klucz interfejsu API znajdziesz na stronie Dane logowania w sekcji Klucze API.
   (Pamiętaj, aby ograniczyć dostęp do klucza API przed użyciem go w produkcji).

Pakiet SDK Cloud

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

Dowiedz się więcej o pakiecie Google Cloud SDK, instalacji Cloud SDK i tych poleceniach:

• gcloud alpha services api-keys create

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji opisujemy, jak przechowywać klucz interfejsu API, aby Twoja aplikacja mogła bezpiecznie się do niego odwoływać. Nie należy go dodawać do systemu 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 usprawnić to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych na Androida.

Uwaga: aby poznać najnowsze wymagania systemowe i instrukcje instalacji, zapoznaj się z dokumentacją Wtyczka Gradle obiektów tajnych na Androida na GitHubie.

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

1. W Android Studio otwórz najwyższy poziom pliku build.gradle.kts lub build.gradle i dodaj pod elementem buildscript kod:dependencies

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

   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 sprawdź, czy wartości targetSdk i compileSdk są ustawione na 34.
4. Zapisz plik i zsynchronizuj projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a potem dodaj ten kod: Zastąp YOUR_API_KEY swoim kluczem API. Przechowuj klucz w tym pliku, ponieważ secrets.properties nie jest uwzględniany w systemie kontroli wersji.
   Uwaga: jeśli plik secrets.properties nie istnieje, utwórz go w tym samym folderze, w którym znajduje się plik local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. Zapisz plik.

7. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, czyli w tym samym folderze co plik secrets.properties, a potem dodaj podany niżej kod.

   Uwaga: wpisz kod zgodnie z wyświetlanymi instrukcjami. Nie zastępuj DEFAULT_API_KEY swoim kluczem API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik stanowi kopię zapasową klucza interfejsu API na wypadek, gdyby nie udało się znaleźć plikusecrets.properties, dzięki czemu kompilacje nie będą się załamywać. Może się tak zdarzyć, jeśli skopiujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties, a na komputerze lokalnym nie masz jeszcze utworzonego pliku secrets.properties, aby podać klucz interfejsu API.

8. Zapisz plik.
9. 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 zalecane nazwa metadanych klucza interfejsu API. Klucza o tej nazwie można używać do uwierzytelniania w wielu interfejsach API opartych na Mapach Google na platformie Androida, w tym w pakiecie SDK Map na Androida. Ze względu na zgodność wsteczną interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ten starszy identyfikator umożliwia uwierzytelnianie tylko w ramach interfejsu Mapy Google na Androida w wersji 2. Aplikacja może podać tylko jedną z nazwy metadanych klucza interfejsu API. Jeśli podasz obie wartości, interfejs API zwróci wyjątek.

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

    Zmień właściwości wtyczki, aby ustawić wartość propertiesFileName na secrets.properties, wartość defaultPropertiesFileName na local.defaults.properties i ustawić 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"
    
        // 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.*"
    }
            

    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"
    
        // 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.*"
    }
            

Sprawdzanie kodu

Sprawdź kod dostarczony przez szablon. Zwróć szczególną uwagę na te pliki w projekcie Android Studio:

Plik z danymi o aktywności w Mapach

Plik aktywności w Mapach to główna aktywność aplikacji. Zawiera kod do zarządzania mapą i jej wyświetlania. Domyślnie plik definiujący aktywność ma nazwę MapsActivity.java lub, jeśli językiem aplikacji jest 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 udostępnia dane mapy i widok. To główna klasa pakietu Maps SDK na Androida. Więcej informacji o obiektach SupportMapFragment i GoogleMap znajdziesz w przewodniku Obiekty mapy.

• 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 Aparat i widok.

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

Plik Gradle modułu

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

dependencies {

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

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

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

Plik układu XML

Plik activity_maps.xml to plik układu XML, który definiuje strukturę interfejsu użytkownika 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 map.

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 uruchomieniu aplikacji wyświetli się mapa wyśrodkowana na Sydney w Australii ze znacznikiem na tym mieście, jak widać na poniższym 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 komputera.
   • Możesz też kliknąć przycisk Uruchom emulator i wybrać skonfigurowane urządzenie wirtualne.
3. Kliknij OK. Android Studio uruchomi Gradle, aby skompilować aplikację, a potem 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ć ustawienia początkowe i ustawienia czasu wykonywania mapy, takie jak pozycja kamery, typ mapy, komponenty interfejsu i gesty.

• Dodawanie mapy do aplikacji na Androida (Kotlin): w tym laboratorium programistycznym znajdziesz aplikację, która demonstruje dodatkowe funkcje pakietu Maps SDK na Androida.

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