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.

To krótkie wprowadzenie jest przeznaczone dla programistów aplikacji na Androida, którzy znają podstawy programowania 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.

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.

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

  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.

    • Ustaw Minimalną wersję pakietu SDK na wersję 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.

    • Ustaw Język konfiguracji kompilacji na Kotlin DSL lub Groovy DSL. Poniżej znajdziesz fragmenty kodu dla obu języków konfiguracji kompilacji.

  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ść w widokach Map Google:

      Menu kontekstowe Android Studio dla folderu aplikacji z wybranymi opcjami Nowy, Google i Aktywność widoków Map 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.

Konfigurowanie projektu Google Cloud

Wykonaj te wymagane czynności konfiguracyjne w konsoli Cloud:

Krok 1. Skonfiguruj projekt

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

Krok 2. Włącz interfejsy API lub pakiety SDK

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:

Krok 3. Uzyskaj klucz interfejsu API

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ć nowy klucz lub dodać interfejs API bądź pakiet SDK do istniejącego klucza, wykonaj te instrukcje.

Konsola

  1. Otwórz stronę Google Maps Platform > Klucze i dane logowania.

    Otwórz stronę Klucze i dane uwierzytelniające

  2. Jeśli pojawi się taka prośba, wybierz projekt.

  3. Wykonaj jedną z tych czynności:

    • Utwórz nowy klucz:

      1. Kliknij Utwórz dane logowania > Klucz interfejsu API.
      2. W panelu Utwórz klucz interfejsu API otwórz listę Wybierz ograniczenia interfejsu API.
      3. Odznacz wszystkie interfejsy API, których ten klucz nie potrzebuje, i upewnij się, że opcja Maps SDK na Androida jest zaznaczona.
      4. Kliknij Utwórz. W panelu pojawi się nowy klucz interfejsu API.

    • Użyj istniejącego klucza:

      1. Kliknij nazwę klucza.
      2. Na liście Wybierz ograniczenia interfejsów API wybierz Maps SDK na Androida.
      3. Kliknij Zapisz.

    Wybranie interfejsu API w tym miejscu nie powoduje jego włączenia. Upewnij się, że pakiet Maps SDK na Androida jest włączony na stronie Biblioteka API.

  4. Aby później wyświetlić ciąg klucza, otwórz stronę Klucze i dane uwierzytelniające i kliknij Pokaż klucz.

Jeśli konsola wygląda inaczej niż w tych krokach, zapoznaj się z artykułami Tworzenie klucza interfejsu API i Dodawanie ograniczeń interfejsu API w dokumentacji Google Cloud.

Pakiet SDK Cloud

W poniższych poleceniach zastąp PROJECT_ID identyfikatorem swojego projektu.

  • Utwórz nowy klucz: uruchom to polecenie i zastąp DISPLAY_NAME nazwą klucza. 

    gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=maps-android-backend.googleapis.com

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

  • Użyj istniejącego klucza: uruchom to polecenie i zastąp KEY_ID identyfikatorem klucza. Flaga --append zachowuje interfejsy API, które klucz już dopuszcza. Bez niego polecenie zastępuje je.

    gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=maps-android-backend.googleapis.com

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

    Identyfikator klucza nie jest ciągiem klucza ani wyświetlaną nazwą. Aby go znaleźć, uruchom gcloud services api-keys list --project="PROJECT_ID". Identyfikator to ostatnia część pola name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

Aby zobaczyć ciąg klucza, uruchom gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

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

    MAPS_API_KEY=DEFAULT_API_KEY

    Ten plik służy do podania zapasowej lokalizacji klucza interfejsu API, jeśli nie uda się znaleźć pliku secrets.properties, aby nie doszło do niepowodzenia kompilacji. 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 oba, 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"
}

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

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

Zrzut ekranu z mapą i znacznikiem wyśrodkowanymi na Sydney w Australii.

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