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ć, przeczytaj artykuł Konfigurowanie projektu w Android Studio.

Uwaga: w tym krótkim wprowadzeniu używamy szablonu Aktywność widoków Map Google, który tworzy układ XML z elementem SupportMapFragment. Jeśli tworzysz interfejs użytkownika za pomocą Jetpack Compose, użyj biblioteki Maps Compose.

To krótkie wprowadzenie jest przeznaczone dla programistów aplikacji na Androida, którzy znają podstawy programowania aplikacji na Androida w Kotlinie lub Javie.

Informacje o środowisku programistycznym

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

Uwaga: jeśli w środowisku programistycznym używasz innej wersji Android Studio lub Gradle, być może będziesz musiał(a) zmodyfikować te czynności. 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ę korzystającą z pakietu Maps SDK na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub emulatorze Androida, który jest oparty na Androidzie 6.0 lub nowszym i zawiera interfejsy Google API.

• Aby używać urządzenia z Androidem, postępuj zgodnie z instrukcjami w artykule Uruchamianie aplikacji na urządzeniu fizycznym.
• 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żywać emulatora Androida, wybierz profil urządzenia z ikoną Play,, która jest wyświetlana w kolumnie Sklep Play. Ta ikona oznacza że te profile są w pełni CTS i mogą używać obrazów systemu, które zawierają aplikację Sklep 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 w kategorii Phone and Tablet wybierz No Activity, a następnie kliknij Next.

3. Wypełnij formularz New Project (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 Kotlinie znajdziesz w artykule Tworzenie aplikacji na Androida w Kotlinie.

   • Ustaw Minimum SDK (Minimalny pakiet SDK) na wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję nowszą niż minimalna wersja wymagana przez pakiet Maps SDK na Androida w wersji 20.0.x, czyli poziom interfejsu API Androida 23 („Marshmallow”; Android 6.0) lub nowszy. Najnowsze informacje o wymaganiach dotyczących wersji pakietu SDK znajdziesz w informacjach o wersji.

     Uwaga: jeśli nie wiesz, którą wersję Android SDK wybrać, kliknij link Help me choose (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), Twoja aplikacja powinna działać na ponad 99% urządzeń z Androidem.

   • Ustaw Build configuration language (Język konfiguracji kompilacji) na Kotlin DSL lub Groovy DSL. W kolejnych procedurach pokazujemy fragmenty kodu w obu językach konfiguracji kompilacji.

4. Kliknij Zakończ.

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

5. Dodaj aktywność widoków Map Google:

   1. Kliknij prawym przyciskiem myszy folder app w projekcie.

   2. Wybierz New > Google > Google Maps Views Activity (Nowy > Google > Aktywność widoków Map Google).

      

   3. W oknie New Android Activity (Nowa aktywność Androida) zaznacz pole wyboru Launcher Activity (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 ta, którą skonfigurowano podczas instalacji.

   Uwaga: plik AndroidManifest.xml zawiera instrukcje dotyczące uzyskiwania klucza interfejsu API Map Google i dodawania go do pliku local.properties. Nie dodawaj klucza interfejsu API do pliku local.properties file. Zamiast tego postępuj zgodnie z instrukcjami w sekcjach Konfigurowanie projektu Google Cloud i Dodawanie klucza interfejsu API do aplikacji, aby zapisać klucz interfejsu API w osobnym secrets.properties pliku za pomocą wtyczki Gradle obiektów tajnych dla Androida.

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 projektu kliknij Utwórz projekt , aby rozpocząć tworzenie nowego projektu Cloud.

   Otwórz stronę selektora projektu

2. Sprawdź, czy w projekcie w chmurze włączone są płatności. Potwierdź, że w projekcie włączone są płatności.

   Google Cloud oferuje bezpłatny okres próbny. Okres próbny wygasa po 90 dniach lub po naliczeniu na koncie opłat w wysokości 300 USD – w zależności od tego, co nastąpi wcześniej. Anuluj kiedy chcesz. Więcej informacji znajdziesz w artykułach Środki na koncie rozliczeniowym i Rozliczenia.

Pakiet SDK Cloud

gcloud projects create "PROJECT"

Więcej informacji o pakiecie Google Cloud SDK , 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 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łącz pakiet Maps SDK na Androida

Pakiet SDK Cloud

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

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

• gcloud services enable
• gcloud services disable

Krok 3

W tym kroku opisujemy 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 Używanie 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 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 Google Cloud SDK , instalacji pakietu SDK Cloud i tych poleceniach:

• 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 dodawać klucza interfejsu API do systemu 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 Pliki właściwości Gradle.

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

   Groovy

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

   Groovy

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

3. Jeśli używasz Android Studio, zsynchronizuj swój projekt z Gradle.
4. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj ten kod. Zastąp YOUR_API_KEY kluczem interfejsu API. Pamiętaj, aby dodać secrets.properties do swojego .gitignore pliku (lub w inny sposób wykluczyć go z systemu kontroli wersji), aby nie dodawać klucza interfejsu API do 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, w tym samym folderze co plik secrets.properties, a następnie dodaj ten kod.

   Uwaga: wpisz kod tak, jak pokazano. Nie zastępuj DEFAULT_API_KEY kluczem interfejsu API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik ma na celu zapewnienie lokalizacji kopii zapasowej klucza interfejsu API jeśli plik secrets.properties nie zostanie znaleziony, aby kompilacje nie kończyły się niepowodzeniem. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji , który pomija secrets.properties i nie masz jeszcze lokalnie utworzonego pliku secrets.properties z kluczem 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 Android, w tym w pakiecie Maps SDK na Androida. Aby zachować 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ą z nazw metadanych klucza interfejsu API. Jeśli określone są obie, 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", ustaw defaultPropertiesFileName na "local.defaults.properties", i 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"
   }

   Groovy

   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, sprawdź, czy w projekcie Google Cloud jest włączony pakiet Maps SDK na Androida i czy klucz interfejsu API w scalonym pliku AndroidManifest.xml jest prawidłowy.

Sprawdzanie kodu

Sprawdź kod dostarczony przez szablon. W szczególności przyjrzyj się tym plikom 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 lub MapsActivity.kt, jeśli jako język aplikacji ustawisz Kotlin.

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. 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. Więcej informacji znajdziesz w przewodniku Kamera i widok.

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

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

Groovy

dependencies {

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

Jeśli Twój projekt używa 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ę różnić 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 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 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 tym mieście, jak pokazano na zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

1. W Android Studio kliknij opcję menu Run (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ż wybrać opcję Launch emulator (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 emulatorze. Uruchomienie aplikacji może potrwać kilka minut.

Dalsze kroki

• Konfigurowanie mapy: w tym dokumencie opisujemy, jak skonfigurować ustawienia początkowe i środowiska wykonawczego mapy, takie jak pozycja kamery, typ mapy, komponenty interfejsu i gesty.

• Dodawanie mapy do aplikacji na Androida (Kotlin): w tym ćwiczeniu w Codelabs przeprowadzimy Cię przez aplikację, która pokazuje 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.