Krótkie wprowadzenie do Maps SDK na Androida

Stwórz aplikację na Androida, która wyświetla mapę, używając w Android Studio szablonu Zdjęć w Mapach Google. 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, którzy znają podstawowe umiejętności programowania Androida w Kotlin lub Javie.

Informacje o środowisku programistycznym

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

Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację, która korzysta z pakietu SDK Map Google na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub w emulatorze Androida w wersji 4.0 lub nowszej, która zawiera interfejsy API Google.

  • Aby używać urządzenia z Androidem, wykonaj instrukcje opisane w artykule Uruchamianie aplikacji na urządzeniu sprzętowym.
  • Jeśli chcesz użyć emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować go za pomocą Menedżera urządzeń wirtualnych (AVD) Android dołączonego do Android Studio.

Tworzenie projektu Map Google w Android Studio

Procedura tworzenia projektu Map Google w Android Studio została zmieniona we Flamingo i nowszych wersjach Android Studio.

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

  2. W oknie Nowy projekt w kategorii Telefon i tablet wybierz Brak aktywności i kliknij 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 SDK Map Google na Androida. Więcej informacji o Kotlin znajdziesz w artykule o tworzeniu aplikacji na Androida przy użyciu usługi Kotlin.

    • Ustaw Minimalny pakiet SDK na wersję SDK zgodną z urządzeniem testowym. Musisz wybrać wersję wyższą niż minimalna wersja wymagana przez pakiet Maps SDK na Androida w wersji 18.2.x, czyli Android API na poziomie 19 („KitKat” lub Androida 4.4) lub nowszej. 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. Fragmenty kodu 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ść wyświetleń w Mapach Google:

    1. Kliknij prawym przyciskiem myszy folder app w projekcie.

    2. Wybierz Nowy > Google > Aktywność wyświetleń w Mapach Google.

      Dodaj aktywność na mapach.

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

    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ą skonfigurujesz podczas konfiguracji.

Skonfiguruj projekt Google Cloud

Wykonaj wymagane kroki konfiguracji Cloud Console, klikając następujące 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.

    Wersja próbna Google Cloud oferuje 0,00 USD. Okres próbny kończy się po 90 dniach lub po naliczeniu opłat w wysokości 300 USD, w zależności od tego, co nastąpi wcześniej. Anuluj, kiedy chcesz. Google Maps Platform oferuje cykliczną miesięczną kwotę promocyjną w wysokości 200 USD. Więcej informacji znajdziesz w sekcjach Środki na koncie rozliczeniowym i Płatności.

(pakiet) SDK Cloud

gcloud projects create "PROJECT"

Dowiedz się więcej o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i o następujących poleceniach:

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"

Dowiedz się więcej o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i o następujących poleceniach:

Krok 3

Ten krok przechodzi tylko przez proces 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 dotyczącej konkretnej usługi.

Klucz interfejsu API to unikalny identyfikator, który uwierzytelnia żądania powiązane z Twoim projektem na potrzeby wykorzystania 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 pojawi się na stronie Dane logowania w sekcji Klucze interfejsu API.
    Zanim użyjesz klucza interfejsu API w środowisku produkcyjnym, ogranicz jego użycie.

(pakiet) SDK Cloud

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

Dowiedz się więcej o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud i o następujących poleceniach:

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji opisujemy, jak zapisać klucz interfejsu API, aby aplikacja mogła bezpiecznie się do niego odwoływać. Nie należy sprawdzać klucza interfejsu API w systemie kontroli wersji, dlatego 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 uprościć to zadanie, zalecamy korzystanie z wtyczki Gradle obiektów tajnych na Androida.

Aby zainstalować wtyczkę Secrets Gradle na Androida w projekcie Map Google:

  1. W Android Studio otwórz plik build.gradle lub build.gradle.kts najwyższego poziomu i dodaj ten 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 do elementu plugins poniższy kod.

    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 i dodaj ten kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Zapisz klucz w tym pliku, ponieważ adres secrets.properties nie jest rejestrowany w systemie kontroli wersji. 
    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.

    MAPS_API_KEY=DEFAULT_API_KEY

    Ten plik służy do podania lokalizacji kopii zapasowej klucza interfejsu API na wypadek, gdyby nie udało się znaleźć pliku secrets.properties, co pozwoli uniknąć błędów kompilacji. Może się tak zdarzyć, jeśli sklonujesz aplikację z systemu kontroli wersji, który pomija element secrets.properties, i nie utworzyłeś jeszcze lokalnie pliku secrets.properties zawierającego Twój klucz interfejsu API.

  8. Zapisz plik.
  9. W pliku AndroidManifest.xml przejdź do 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 dostarczony z szablonem. W szczególności zwróć uwagę na te pliki w projekcie Android Studio.

Plik aktywności w Mapach

Plik aktywności na mapach to główna aktywność w aplikacji i zawiera kod umożliwiający zarządzanie mapą i jej wyświetlanie. Domyślnie plik definiujący aktywność to MapsActivity.java. Jeśli ustawisz Kotlin jako język aplikacji, MapsActivity.kt.

Najważniejsze elementy działań na mapach:

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

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

  • Funkcja moveCamera wyśrodkowuje mapę na współrzędnych LatLng dla Sydney Australia. Pierwszymi ustawieniami, jakie należy skonfigurować przy dodawaniu mapy, są lokalizacja mapy i ustawienia aparatu, takie jak kąt widzenia, orientacja mapy i poziom powiększenia. Więcej informacji znajdziesz w przewodniku Aparat i widok.

  • Funkcja addMarker dodaje znacznik do współrzędnych lokalizacji Sydney. Szczegółowe informacje 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 Map Google na Androida.

dependencies {

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

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 określa strukturę UI 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 określona w pliku aktywności związanej z mapami.
  • android:name ustawia nazwę klasy fragmentu na SupportMapFragment, czyli typ fragmentu używany w pliku aktywności mapy.

Plik układu XML zawiera następujący 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 w regionie Syndney Australia.

Po uruchomieniu aplikacji wyświetli się mapa ze znacznikiem miasta Sydney Australia ze znacznikiem widocznym na poniższym zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

  1. W Android Studio kliknij opcję menu Uruchom (lub ikonę przycisku odtwarzania), by uruchomić aplikację.
  2. Gdy pojawi się prośba o wybranie urządzenia, wybierz jedną z tych opcji:
    • Wybierz urządzenie z Androidem, które jest połączone z Twoim komputerem.
    • Możesz też zaznaczyć opcję 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. Zanim aplikacja zostanie uruchomiona, może upłynąć kilka minut.

Dalsze kroki