Krótkie wprowadzenie do Maps SDK na Androida

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

To krótkie wprowadzenie jest przeznaczone dla programistów znających podstawowe programowanie na Androida z użyciem Kotlin lub Javy.

Informacje o środowisku programistycznym

To krótkie wprowadzenie zostało opracowane przy użyciu Android Studio Hedgehog i wtyczki Android Gradle w wersji 8.2.

Uwaga: jeśli w Twoim środowisku programistycznym używana jest inna wersja Android Studio lub Gradle, konieczne może być zmodyfikowanie instrukcji w zależności od środowiska. Więcej informacji o wersjach Android Studio i Gradle znajdziesz w artykule o wtyczce Android do obsługi Gradle i zgodności z Androidem Studio.

Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację, która korzysta z pakietu SDK Maps na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub w emulatorze Androida opartym na Androidzie 4.0 lub nowszym i zawierającym interfejsy API Google.

• Aby używać urządzenia z Androidem, wykonaj instrukcje opisane w artykule Uruchamianie aplikacji na urządzeniu sprzętowym.
• Aby użyć emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować go za pomocą Menedżera urządzeń wirtualnych Android (AVD) dołączonego do Android Studio.
  Uwaga: jeśli zdecydujesz się użyć emulatora Androida, wybierz urządzenie z ikoną Play widoczną w kolumnie Sklep Play. Ta ikona oznacza, że te profile są w pełni zgodne z CTS i mogą używać obrazów systemu zawierających aplikację Sklep Play:

  

Tworzenie projektu Map Google w Android Studio

Procedura tworzenia projektu Map Google w Android Studio zmieniła się w wersji Flamingo i nowszych wersjach Android Studio.

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

2. W oknie New Project (Nowy projekt) w kategorii Telefony i tablety wybierz Brak aktywności, a następnie kliknij Dalej.

3. Wypełnij formularz New Project (Nowy projekt):

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

   • Ustaw Minimalny pakiet SDK na wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję wyższą niż minimalna wersja wymagana przez pakiet SDK Maps na Androida w wersji 18.2.x, czyli interfejsu API Androida na poziomie 19 („KitKat”; Android 4.4) lub nowszym. 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 dotyczące dystrybucji obsługiwanych pakietów SDK na Androida. Jeśli na przykład wybierzesz Android API Level 19 („KitKat”; Android 4.4), Twoja aplikacja powinna działać na ponad 99% urządzeń z Androidem.

   • Jako Język konfiguracji kompilacji ustaw Kotlin DSL lub Groovy DSL. Fragmenty dla obu języków konfiguracji kompilacji są wyświetlane w poniższych procedurach.

4. Kliknij Zakończ.

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

5. Dodaj Aktywność związaną z zdjęciami w Mapach Google:

   1. Kliknij prawym przyciskiem myszy folder app w projekcie.

   2. Wybierz Nowy > Google > Aktywność w Mapach Google.

      

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

   4. Wybierz Zakończ.

      Więcej informacji znajdziesz w artykule o dodawaniu kodu z szablonu.

6. Po zakończeniu kompilacji Android Studio otworzy pliki AndroidManifest.xml i MapsActivity. Aktywność może mieć inną nazwę, ale ta skonfigurowana podczas konfiguracji.

   Uwaga: plik AndroidManifest.xml zawiera instrukcje uzyskania klucza interfejsu API Map Google i dodania go do pliku local.properties. Nie dodawaj klucza interfejsu API do pliku local.properties. Dzięki temu klucz interfejsu API jest przechowywany w mniej bezpieczny sposób. Zamiast tego wykonaj instrukcje opisane w artykule Konfigurowanie projektu Google Cloud, aby utworzyć projekt Cloud i skonfigurować klucz interfejsu API.

Skonfiguruj projekt Google Cloud

Wykonaj wymagane czynności konfiguracyjne w Cloud Console, 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 okres próbny w wysokości 0,00 USD. 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). W każdej chwili możesz anulować subskrypcję. Google Maps Platform oferuje cykliczne środki w wysokości 200 USD miesięcznie. Więcej informacji znajdziesz w artykułach Środki na koncie rozliczeniowym i Płatności.

(pakiet) SDK Cloud

gcloud projects create "PROJECT"

Przeczytaj więcej o Google Cloud SDK, instalacji pakietu SDK Cloud i poniższych poleceniach:

• gcloud projects create

Uwaga: jeśli nie planujesz zachować utworzonych zasobów w trakcie ćwiczenia, zamiast wybierać istniejący projekt, utwórz projekt. Po zakończeniu ćwiczenia możesz usunąć projekt wraz ze wszystkimi zasobami, które są z nim powiązane.

Krok 2

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

Konsola

Włączanie Maps SDK na Androida

(pakiet) SDK Cloud

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

Przeczytaj więcej o Google Cloud SDK, instalacji pakietu SDK Cloud i poniższych poleceniach:

• gcloud services enable
• gcloud services disable

Krok 3

Ten krok wykonuje się tylko w procesie tworzenia klucza interfejsu API. Jeśli używasz klucza interfejsu API w środowisku produkcyjnym, zdecydowanie zalecamy ograniczenie klucza interfejsu API. Więcej informacji znajdziesz na stronie Używanie kluczy interfejsu API w przypadku konkretnej usługi.

Klucz interfejsu API to unikalny identyfikator, który uwierzytelnia żądania powiązane z Twoim projektem na potrzeby użytkowania i rozliczeń. Musisz mieć co najmniej 1 klucz interfejsu API powiązany z projektem.

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 znajdziesz na stronie Dane logowania w sekcji Klucze interfejsu API.
   (Pamiętaj, aby ograniczyć klucz interfejsu API, zanim użyjesz go w środowisku produkcyjnym.

(pakiet) SDK Cloud

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

Przeczytaj więcej o Google Cloud SDK, instalacji pakietu SDK Cloud i poniższych poleceniach:

• gcloud alpha services api-keys create

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji opisujemy, jak zapisać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie należy sprawdzać klucza interfejsu API w systemie kontroli wersji, więc zalecamy zapisanie go w pliku secrets.properties, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku secrets.properties znajdziesz w artykule o plikach właściwości Gradle.

Aby usprawnić to zadanie, zalecamy korzystanie z wtyczki do Gradle obiektów tajnych na Androida.

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

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

1. W Android Studio otwórz plik build.gradle lub build.gradle.kts najwyższego poziomu i dodaj poniższy kod do elementu dependencies w sekcji buildscript.

   Zakręcony

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }
   

2. Otwórz plik build.gradle na poziomie modułu i dodaj poniższy kod do elementu plugins.

   Zakręcony

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

   plugins {
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

3. W pliku build.gradle na poziomie modułu sprawdź, czy targetSdk i compileSdk mają wartość 34.
4. Zapisz plik i zsynchronizuj projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj poniższy kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Zapisz 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. Zapisz plik.

7. Utwórz plik local.defaults.properties w katalogu najwyższego poziomu, w tym samym folderze co plik secrets.properties, a następnie dodaj poniższy kod.

   Uwaga: wpisz kod, który wyświetla się poniżej. Nie zastępuj DEFAULT_API_KEY kluczem interfejsu API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik zawiera kopię zapasową klucza interfejsu API na wypadek, gdyby plik secrets.properties nie został znaleziony. Pozwala to uniknąć błędu kompilacji. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija atrybut secrets.properties, i nie masz jeszcze lokalnego pliku secrets.properties umożliwiającego przekazanie klucza interfejsu API.

8. Zapisz plik.
9. W pliku AndroidManifest.xml przejdź do sekcji 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}" />

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

Spójrz na kod

Sprawdź kod w szablonie. W szczególności przyjrzyj się poniższym plikom w projekcie w Android Studio.

Plik aktywności w Mapach

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

Główne elementy aktywności związanej z mapami:

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

• Obiekt GoogleMap zapewnia dostęp do danych i widoku mapy. To jest główna klasa pakietu SDK Maps na Androida. Przewodnik po obiektach mapy zawiera bardziej szczegółowe informacje o obiektach SupportMapFragment i GoogleMap.

• Funkcja moveCamera wyśrodkowuje mapę na współrzędnych LatLng dla Sydney Australia. Pierwsze ustawienia do skonfigurowania przy dodawaniu mapy to zwykle ustawienia lokalizacji na mapie i aparatu, takie jak kąt patrzenia, orientacja mapy czy poziom powiększenia. Więcej informacji znajdziesz w przewodniku Aparat i widok.

• Funkcja addMarker dodaje znacznik do współrzędnych Sydney. Więcej informacji znajdziesz w przewodniku Znaczniki.

Plik Gradle modułu

Plik modułu build.gradle zawiera podaną niżej zależność map, która jest wymagana przez pakiet SDK Maps na Androida.

dependencies {

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

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

Aby dowiedzieć się więcej o zarządzaniu zależnością Map, przeczytaj artykuł na temat obsługi wersji.

Plik układu XML

Plik activity_maps.xml to plik układu XML definiujący strukturę interfejsu użytkownika aplikacji. Plik znajduje się w katalogu res/layout. Plik activity_maps.xml deklaruje fragment zawierający te elementy:

• tools:context ustawia domyślną aktywność tego fragmentu na MapsActivity, która jest definiowana 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" />

Wdróż i uruchom aplikację

Po uruchomieniu aplikacji wyświetli się mapa wyśrodkowana na Sydney w Australii ze znacznikiem na mieście, tak jak na zrzucie ekranu poniżej.

Aby wdrożyć i uruchomić aplikację:

1. W Android Studio kliknij w menu opcję 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ż zaznaczyć 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 w emulatorze. Uruchomienie aplikacji może potrwać kilka minut.

Dalsze kroki

• Konfigurowanie mapy: w tym dokumencie opisujemy, jak skonfigurować początkowe ustawienia i czas działania mapy, np. pozycję kamery, typ mapy, komponenty interfejsu i gesty.

• Dodawanie mapy do aplikacji na Androida (Kotlin): dzięki temu ćwiczeniu w Codelabs dowiesz się, jak korzystać z aplikacji, w której poznasz niektóre dodatkowe funkcje pakietu Maps SDK na Androida.

• Skorzystaj z biblioteki Maps Android KTX: Dzięki tej bibliotece rozszerzeń Kotlin (KTX) możesz korzystać z kilku funkcji językowych Kotlin, korzystając z pakietu Maps SDK na Androida.