Krótkie wprowadzenie do Maps SDK na Androida

Stwórz aplikację dla Androida wyświetlającą mapę, korzystając ze Zdjęć w Mapach Google dla Android Studio. Jeśli masz już projekt w Android Studio, które chcesz skonfigurować, przeczytaj artykuł Konfigurowanie projektu Android Studio.

To krótkie wprowadzenie jest przeznaczone dla programistów znających Programowanie 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 oraz 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 użyć urządzenia z Androidem, postępuj zgodnie z instrukcjami na stronie Uruchamianie aplikacji na urządzeniu
• 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, upewnij się, że wybierzesz urządzenie z ikoną Play, , widoczną w kolumnie Sklep Play. Ta ikona oznacza, że te profile są w pełni wyposażone w CTS. zgodne z zasadami i mogą używać obrazów systemu zawierających 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 kliknij New Project (Nowy projekt) w Okno Witamy w Android Studio.

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 SDK Maps na Androida. Więcej informacji o Kotlin znajdziesz na stronie Tworzenie aplikacji na Androida za pomocą Kotlin

   • Ustaw minimalny pakiet SDK na wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję wyższą niż minimalna wersja wymagana przez Maps SDK na Androida w wersji 19.0.x, – Android API poziomu 21 („Lollipop”; Android 5.0) lub nowszy. 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 Android API Level 21 („Lollipop”; Android 5.0), aplikacja powinna działać ponad 99% urządzeń z Androidem.

   • Jako Język konfiguracji kompilacji ustaw 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 zdjęciami w Mapach Google:

   1. Kliknij prawym przyciskiem myszy 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: Dodawanie kodu z szablonu

6. Po zakończeniu kompilacji Android Studio otwiera okno AndroidManifest.xml i MapsActivity plików. Aktywność może mieć inną nazwę, ale to adres skonfigurowany podczas konfiguracji.

   Uwaga: plik AndroidManifest.xml zawiera instrukcje pobierania Klucz interfejsu API Map Google, a następnie dodanie 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 postępuj zgodnie z instrukcjami w artykule Konfigurowanie projektu Google Cloud, aby utworzyć projekt Cloud. skonfigurować klucz interfejsu API.

Skonfiguruj projekt 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 projekcie są włączone płatności.

   Google Cloud oferuje okres próbny w wysokości 0,00 USD. 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 każdej chwili. Google Maps Platform oferuje cykliczne środki w wysokości 200 USD miesięcznie. Więcej Więcej informacji zawiera Środki na koncie rozliczeniowym i Płatności.

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 nie planujesz zachować utworzonych zasobów utworzyć projekt, zamiast wybierać istniejący. Po zakończeniu możesz usunąć projekt, usuwając wszystkie powiązane z nim zasoby.

Krok 2

Aby używać Google Maps Platform, musisz włączyć interfejsy API lub pakiety SDK, których chcesz używać w projekcie.

Konsola

Włączanie Maps SDK na Androida

Pakiet SDK Cloud

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

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

• gcloud services enable
• gcloud services disable

Krok 3

Ten krok wykonuje się tylko w procesie tworzenia klucza interfejsu API. Jeśli używasz klucza interfejsu API w w środowisku produkcyjnym zdecydowanie zalecamy ograniczenie klucza interfejsu API. 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, który uwierzytelnia żądania powiązane z projektem w: użytkowania i rozliczeń. Musisz mieć co najmniej 1 klucz interfejsu API powiązany z projektem.

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 > 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 o ograniczeniu dostępu do interfejsu API przed użyciem w środowisku produkcyjnym).

Pakiet SDK Cloud

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

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

• gcloud alpha services api-keys create

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji opisano, jak zapisać klucz interfejsu API, aby umożliwić bezpieczne korzystanie z niego do aplikacji. Nie sprawdzaj klucza interfejsu API w systemie kontroli wersji, dlatego zalecamy i przechowywanie go w pliku secrets.properties, który znajduje się w katalogu głównym instancji w projektach AI. Więcej informacji o pliku secrets.properties znajdziesz tutaj: Pliki właściwości Gradle.

Aby usprawnić to zadanie, zalecamy skorzystanie z Wtyczka Gradle obiektów tajnych na Androida.

Uwaga: zapoznaj się z Wtyczka Gradle obiektów tajnych dla Androida dokumentacji w serwisie GitHub zawierającej najnowsze wymagania systemowe i instrukcje instalacji.

Aby zainstalować wtyczkę Gradle obiektów tajnych na Androida w projekcie Map Google:

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

   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 oraz compileSdk mają wartość 34.
4. Zapisz plik i zsynchronizować projekt z Gradle.
5. Otwórz plik secrets.properties w katalogu najwyższego poziomu, a następnie dodaj atrybut 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 utwórz 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, który wyświetla się poniżej. Nie zastępuj DEFAULT_API_KEY za pomocą klucza interfejsu API.

   MAPS_API_KEY=DEFAULT_API_KEY

   Ten plik ma na celu udostępnienie zapasowej lokalizacji klucza interfejsu API, jeśli plik Nie znaleziono pliku secrets.properties, więc kompilacje nie zawierają błędów. 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}" />

   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 w szablonie. W szczególności zwróć uwagę na te kwestie: w projekcie w Android Studio.

Plik 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 cyklu życia mapy i jest elementem nadrzędnym interfejsu aplikacji.

• Obiekt GoogleMap zapewnia dostęp do danych 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 dla: Sydney. Więcej informacji znajdziesz w przewodniku Znaczniki.

Plik Gradle modułu

Plik modułu build.gradle zawiera następującą zależność map, która: jest wymagany przez pakiet Maps SDK 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ę zmienić w zależności od bieżącej wersji Maps SDK na Androida.

Aby dowiedzieć się więcej o zarządzaniu zależnością Map, przeczytaj artykuł na temat obsługi wersji.

Plik układu XML

Plik activity_maps.xml to plik układu XML, który definiuje do struktury interfejsu 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 wartość MapsActivity, która jest definiowana w pliku aktywności w Mapach.
• android:name ustawia nazwę klasy fragmentu na SupportMapFragment, czyli typ fragmentu używany w aktywności związanej z mapami .

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

Wdróż i uruchom aplikację

Po uruchomieniu aplikacji wyświetli się mapa wyśrodkowana na Sydney Australia ze znacznikiem na mieście, jak widać na poniższym zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

1. W Android Studio kliknij w menu opcję Uruchom (lub ikonę przycisku odtwarzania), aby uruchom 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ż zaznaczyć opcję Uruchom emulator, a potem kliknąć skonfigurowanego przez Ciebie urządzenia wirtualnego.
3. Kliknij OK. Android Studio uruchomi Gradle, aby utworzyć aplikację, a następnie i wyświetlaj wyniki na urządzeniu lub w emulatorze. Aplikacja może uruchomić się po kilku minutach nowych funkcji.

Dalsze kroki

• Skonfiguruj mapę: ten dokument opisuje sposób konfigurowania początkowych i czasowych ustawień mapy, takich jak takie jak pozycja kamery, typ mapy, komponenty interfejsu i gesty.

• Dodawanie mapy do aplikacji na Androida (Kotlin): to ćwiczenie z programowania opisuje aplikację prezentującą dodatkowe funkcje Maps SDK na Androida.

• Użyj biblioteki Map KTX na Androida: Ta biblioteka rozszerzeń Kotlin (KTX) pozwala korzystać z funkcje językowe Kotlin podczas korzystania z pakietu Maps SDK na Androida.