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óre chcesz skonfigurować, przeczytaj artykuł Konfigurowanie projektu 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

To krótkie wprowadzenie zostało opracowane w Android Studio Jeż i Android Wtyczka Gradle wersji 8.2.

Uwaga: jeśli w Twoim środowisku programistycznym używana jest inna wersja Android Studio lub Gradle może być konieczne zmodyfikowanie kroków w zależności od środowiska. Więcej informacje o wersjach Android Studio i Gradle znajdziesz na stronie wtyczki Android do Gradle i Android Studio zgodność.

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 na urządzeniu z Androidem emulator oparty na Androidzie 5.0 lub nowszym i obejmuje interfejsów API Google.

• Aby korzystać z urządzenia z Androidem, wykonaj instrukcje opisane w artykule Uruchamianie aplikacji na urządzeniu z Androidem.
• Aby użyć emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować emulator za pomocą: Menedżer urządzeń wirtualnych z Androidem (AVD), dostępne w 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 pakietem 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 Flamingo i nowsze wersje Android Studio.

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

2. W oknie New Project (Nowy projekt) w kategorii Phone and Tablet (Telefon i tablet) wybierz Brak aktywności i kliknij Dalej.

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

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

   • Ustaw 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 odpowiada poziomowi interfejsu API 21 („Lollipop”, Android 5.0) lub nowszemu. Zapoznaj się z informacjami o wersji Najnowsze informacje o wymaganiach dotyczących wersji pakietu SDK.

     Uwaga: jeśli nie wiesz, którą wersję pakietu SDK wybrać, Link Pomóż mi wybrać do wyświetlania informacji o dystrybucji obsługiwanych Pakiety SDK na 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. Fragmenty obu języków konfiguracji kompilacji są wyświetlane poniżej procedur.

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. Wybierz Nowy > Google > Aktywność związana z Zdjęciami w Mapach Google.

      

   3. W oknie Nowa aktywność na Androidzie wybierz Aktywność programu uruchamiającego.

   4. Wybierz 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ę, ale to adres skonfigurowany podczas konfiguracji.

   Uwaga: plik AndroidManifest.xml zawiera instrukcje uzyskiwania klucza interfejsu API Map Google i dodawania go do pliku local.properties. Należy 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 w artykule Konfigurowanie projektu Google Cloud, aby utworzyć projekt Cloud i skonfigurować klucz interfejsu API.

Konfigurowanie projektu Google Cloud

Zakończ wymagane czynności konfiguracyjne Cloud Console, klikając na tych kartach:

Krok 1

Konsola

1. Na stronie selektora projektów w konsoli Google Cloud kliknij Utwórz projekt, aby rozpocząć tworzenie nowego projektu Cloud. w projektach AI.

   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 kończy się po upływie każdego końca 90 dni lub po naliczeniu na koncie opłat w wysokości 300 USD, zależnie od tego, co nastąpi wcześniej. Anuluj w dowolnym momencie. Google Maps Platform oferuje stałe miesięczne środki w wysokości 200 USD. Więcej informacji znajdziesz w artykułach Środki na koncie rozliczeniowym i Rozliczenia.

Pakiet SDK Cloud

gcloud projects create "PROJECT"

Przeczytaj więcej na temat Pakiet SDK Google Cloud , Instalacja pakietu SDK Cloud oraz tych poleceń:

• 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 swoim 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 wersji produkcyjnej, zdecydowanie zalecamy ograniczenie jego dostępu. Więcej informacji na ten temat znajdziesz na stronie Using API Keys (Używanie kluczy interfejsu API) w danej usłudze.

Klucz interfejsu API to unikalny identyfikator używany do uwierzytelniania żądań powiązanych z projektem na potrzeby wykorzystania i rozliczania. Z projektem musi być powiązany co najmniej 1 klucz interfejsu API.

Aby utworzyć klucz interfejsu API:

Konsola

1. Otwórz 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ć 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 tutaj: 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:

   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ź, że wartości targetSdk i compileSdk są ustawione do 34.
4. Zapisz plik i zsynchronizować projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj tego kodu. Zastąp YOUR_API_KEY swoim kluczem interfejsu API. Przechowuj klucz w tym pliku ponieważ secrets.properties nie jest sprawdzany w kontroli wersji systemu.
   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, tak samo jako plik secrets.properties, a potem dodaj podany niżej kod.

   Uwaga: wpisz kod zgodnie z wyświetlanymi instrukcjami. Nie zastępuj DEFAULT_API_KEY za pomocą klucza interfejsu 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 sklonujesz aplikację z systemu kontroli wersji, który pomija secrets.properties oraz nie utworzyłeś jeszcze lokalnie pliku secrets.properties, który umożliwi przesyłanie 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. Klucz o tej nazwie może być używany do uwierzytelniania w wielu Interfejsy API oparte na Mapach Google na platformie Android, w tym Maps SDK 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 określono oba te parametry, zgłasza 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 w szablonie. W szczególności zwróć uwagę na te kwestie: w projekcie Android Studio.

Plik z danymi o aktywności w Mapach

Plik aktywności w Mapach jest główną aktywnością w aplikacji. który zawiera kod służący do zarządzania mapą i jej wyświetlania. Domyślnie plik zdefiniowane jest działanie o nazwie MapsActivity.java lub jeśli ustawisz Kotlin jako język Twojej aplikacji: MapsActivity.kt.

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

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

• Obiekt GoogleMap udostępnia dane mapy i widok. To jest główna klasa pakietu SDK Maps na Androida. Obiekty mapy Przewodnik opisuje obiekty SupportMapFragment i GoogleMap w bardziej szczegóły.

• Funkcja moveCamera wyśrodkowuje mapę na Współrzędne LatLng dla Sydney Australia. Pierwsze ustawienia skonfigurować podczas dodawania mapy to zwykle lokalizacja na mapie i ustawienia aparatu; takie jak kąt patrzenia, orientacja mapy i poziom powiększenia. Zobacz Przewodnik po aparacie i widoku zawiera szczegółowe informacje.

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

Plik Gradle modułu

Plik Module build.gradle.kts zawiera te zależności od Map, które są wymagane 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 zawierający te elementy 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 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. Aby uruchomić aplikację, w Android Studio kliknij opcję Uruchom (lub ikonę przycisku odtwarzania).
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 komputerami.
   • 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 i wyświetlaj 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 Map na Androida.