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 istniejący projekt Android Studio, który chcesz skonfigurować, zapoznaj się z artykułem Konfigurowanie projektu w Android Studio.

Ten krótki przewodnik jest przeznaczony dla programistów, którzy znają podstawy tworzenia aplikacji na Androida w języku Kotlin lub Java.

Informacje o środowisku programistycznym

Ten krótki przewodnik został opracowany w Android Studio Hedgehog i wtyczce Gradle dla Androida w wersji 8.2.

Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację korzystającą z pakietu SDK Map Google na Androida, musisz wdrożyć ją na urządzeniu z Androidem lub na emulatorze Androida opartym na Androidzie 5.0 lub nowszym, który zawiera interfejsy API Google.

• Aby korzystać z urządzenia z Androidem, wykonaj instrukcje opisane w artykule Uruchamianie aplikacji na urządzeniu z Androidem.
• Aby korzystać z emulatora Androida, możesz utworzyć urządzenie wirtualne i zainstalować emulator za pomocą menedżera urządzenia wirtualnego z Androidem (AVD), który jest częścią Android Studio.

Tworzenie projektu Map Google w Android Studio

Procedura tworzenia projektu Google Maps w Android Studio została zmieniona w wersjach Flamingo i późniejszych wersji Android Studio.

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

2. W oknie Nowy projekt w kategorii Telefony i tablety wybierz Brak aktywności, a potem kliknij Dalej.

3. Wypełnij formularz Nowy projekt:

   • Ustaw 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 opcję Minimalna wersja pakietu 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. Najnowsze informacje o wymaganiach dotyczących wersji pakietu SDK znajdziesz w notatkach do wersji.

   • Ustaw język konfiguracji kompilacji na Kotlin DSL lub Groovy DSL. W następujących procedurach podano fragmenty kodu dla obu języków konfiguracji kompilacji.

4. Kliknij Zakończ.

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

5. Dodaj Aktywność dotyczącą wyświetleń w Mapach Google:

   1. Kliknij prawym przyciskiem myszy folder app w projekcie.

   2. Kliknij Nowe > Google > Aktywność wyświetleń w Mapach Google.

      

   3. W oknie Nowa aktywność na Androida zaznacz pole wyboru Aktywność w edytorze.

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

Konfigurowanie projektu Google Cloud

Wykonaj wymagane czynności konfiguracji konsoli Cloud, klikając kolejno te karty:

gcloud projects create "PROJECT"

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

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

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 w artykule Pliki właściwości Gradle.

Aby uprościć to zadanie, zalecamy użycie wtyczki Gradle obiektów tajnych na Androida.

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:dependencies

   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ź, czy wartości targetSdk i compileSdk są ustawione na 34.
4. Zapisz plik i zsynchronizuj projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a potem dodaj ten kod. Zastąp YOUR_API_KEY swoim kluczem API. Przechowuj klucz w tym pliku, ponieważ secrets.properties nie jest uwzględniany 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, czyli w tym samym folderze co plik secrets.properties, a potem dodaj podany niżej kod.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik stanowi kopię zapasową klucza interfejsu API na wypadek, gdyby nie udało się znaleźć pliku secrets.properties, dzięki czemu kompilacje nie będą się załamywać. Może się tak zdarzyć, jeśli klonujesz aplikację z systemu kontroli wersji, który pomija plik secrets.properties, a na komputerze lokalnym nie masz jeszcze utworzonego pliku secrets.properties, aby podać 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. Klucza o tej nazwie można używać do uwierzytelniania w wielu interfejsach API opartych na Mapach Google na platformie Androida, w tym w 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 podasz obie wartości, interfejs API zwróci 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.*"
    }
            

Sprawdź kod

Sprawdź kod dostarczony przez szablon. Zwróć szczególną uwagę na te pliki w projekcie w Android Studio:

Plik aktywności w Mapach

Plik aktywności w Mapach to główna aktywność aplikacji. Zawiera kod do zarządzania mapą i jej wyświetlania. Domyślnie plik definiujący aktywność ma nazwę MapsActivity.java lub, jeśli w aplikacji ustawisz język 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 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. Szczegółowe informacje znajdziesz w przewodniku Aparat i widok.

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

Plik Gradle modułu

Plik Module build.gradle.kts zawiera tę zależność od 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:19.0.0")
}

Więcej informacji o zarządzaniu zależnością od Map znajdziesz w sekcji Wersje.

Plik układu XML

Plik activity_maps.xml to plik układu XML, który określa 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 map.

Plik XML układu 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

Gdy uruchomisz aplikację, wyświetli się mapa z pośrodku Sydney w Australii z oznacznikiem na miasto, jak na poniższym zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

1. Aby uruchomić aplikację, w Android Studio kliknij opcję menu 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 opcji Uruchom emulator i wybrać skonfigurowane urządzenie wirtualne.
3. Kliknij OK. Android Studio uruchomi Gradle, aby skompilować aplikację, a potem 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ć 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 poznasz 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.