Krótkie wprowadzenie do Maps SDK na Androida

Utwórz aplikację na Androida wyświetlającą mapę, korzystając z szablonu Map Google przeznaczonego do Android Studio. Jeśli masz już projekt Android Studio, który chcesz skonfigurować, przeczytaj artykuł o konfiguracji projektu.

Ten krótki przewodnik jest przeznaczony dla programistów, którzy znają podstawowe programowanie Androida przy użyciu języka Java lub Kotlin.

Konfigurowanie środowiska programistycznego

1. Wymagane jest Android Studio Arctic Fox lub nowsza wersja. Pobierz i zainstaluj aplikację, jeśli jeszcze jej nie masz.
2. Upewnij się, że używasz wtyczki do Androida do obsługi Gradle w Android Studio w wersji 7.0 lub nowszej.

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 emulatorze Androida w wersji 4.0 lub nowszej i zawierającej 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ć emulator za pomocą Menedżera urządzeń wirtualnych Android (AVD) dołączonego do Android Studio.
  Uwaga: jeśli chcesz używać emulatora Androida, wybierz urządzenie z ikoną grania , która jest widoczna w kolumnie Sklep Play. Ta ikona oznacza, że te profile są w pełni zgodne z CTS i mogą korzystać z 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 we Flamingo i późniejszych wersjach Android Studio. Wykonaj instrukcje odpowiednie do swojej wersji Androida Studio.

1. Otwórz Android Studio i kliknij Create New Project (Utwórz nowy projekt) w oknie Witamy w Android Studio.

2. W oknie Nowy projekt w kategorii Telefon i tablet wybierz Pusta aktywność i kliknij Dalej.

   Uwaga: jeśli korzystasz z Android Studio Electric Eel lub starszej wersji, wybierz opcję Aktywność w Mapach Google.

3. Wypełnij formularz Aktywność w Mapach Google:

   • 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 Kotlin znajdziesz w artykule Tworzenie aplikacji na Androida przy użyciu Kotlin.

   • Ustaw Minimalny pakiet SDK na wersję pakietu SDK zgodną z urządzeniem testowym. Musisz wybrać wersję wyższą niż minimalna wymagana przez pakiet Maps SDK na Androida w wersji 18.0.x, czyli Android API na poziomie 19 (Android 4.4, KitKat) lub nowszym. Najnowsze informacje o wymaganiach dotyczących wersji pakietu SDK znajdziesz w informacjach o wersji.

     Uwaga: jeśli nie wiesz, którą wersję pakietu SDK wybrać, kliknij link Pomóż mi wybrać, aby wyświetlić informacje o dystrybucji obsługiwanych pakietów SDK na Androida. Jeśli np. wybierzesz API 19: Android 4.4 (KitKat), aplikacja powinna działać na ponad 99% urządzeń z Androidem.

4. Kliknij Zakończ

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

5. Po zakończeniu kompilacji Android Studio otworzy pliki AndroidManifest.xml i MapsActivity. Aktywność może mieć inną nazwę, ale jest to ta, którą skonfigurowałeś podczas konfiguracji.

6. Dodaj aktywność wyświetleń w Mapach Google:

   Uwaga: pomiń ten krok, jeśli korzystasz z narzędzia Android Studio Electric Eel lub wcześniej, ponieważ w kroku 2 masz wybraną Aktywność w Mapach Google.
   1. Kliknij prawym przyciskiem myszy pakiet, do którego chcesz dodać aktywność dotyczącą wyświetleń w Mapach Google.
   2. Wybierz Nowe > Google > Aktywność wyświetleń w Mapach Google.

   

   Więcej informacji znajdziesz w artykule Dodawanie kodu z szablonu.

7. Plik AndroidManifest.xml zawiera instrukcje dotyczące uzyskania klucza interfejsu API Map Google i dodania go do pliku local.properties. Nie dodawaj klucza interfejsu API do pliku AndroidManifest.xml. Klucz interfejsu API będzie wtedy mniej bezpiecznie przechowywany. Zamiast tego wykonaj instrukcje podane w następnych sekcjach, aby utworzyć projekt Cloud i skonfigurować klucz interfejsu API.

Konfigurowanie projektu Google Cloud

Wykonaj wymagane czynności konfiguracyjne w Cloud Console, klikając te karty:

Krok 1

Konsola

1. W Google Cloud Console na stronie selektora projektów kliknij Utwórz projekt, aby rozpocząć tworzenie nowego projektu Cloud.

   Otwórz stronę wyboru 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 obejmujący 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. Subskrypcję możesz anulować w każdej chwili. W ramach Google Maps Platform otrzymujesz comiesięczne środki 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 oraz tych poleceniach:

• gcloud projects create

Uwaga: jeśli nie zamierzasz zachować zasobów utworzonych w trakcie ćwiczenia, zamiast wybierać istniejący projekt, utwórz nowy. Po zakończeniu ćwiczenia możesz usunąć projekt wraz ze wszystkimi zasobami, które są z nim powiązane.

Krok 2

Aby używać Google Maps Platform, musisz włączyć interfejsy API lub pakiety SDK, których zamierzasz 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"

Dowiedz się więcej o pakiecie SDK Google Cloud, instalacji pakietu SDK Cloud oraz tych poleceniach:

• gcloud services enable
• gcloud services disable

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 Korzystanie z kluczy interfejsu API dotyczącej danej usługi.

Klucz interfejsu API to unikalny identyfikator, który uwierzytelnia żądania powiązane z Twoim projektem w celach związanych z użytkowaniem i rozliczeniami. 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 zostanie wyświetlony 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 przed użyciem klucza interfejsu API ograniczyć 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 oraz tych poleceniach:

• gcloud alpha services api-keys create

Dodawanie klucza interfejsu API do aplikacji

W tej sekcji dowiesz się, jak przechowywać klucz interfejsu API, aby aplikacja mogła się do niego bezpiecznie odwoływać. Nie sprawdzaj klucza interfejsu API w systemie kontroli wersji, dlatego zalecamy zapisanie go w pliku local.properties, który znajduje się w katalogu głównym projektu. Więcej informacji o pliku local.properties znajdziesz w artykule Pliki właściwości Gradle.

Aby ułatwić sobie to zadanie, zalecamy korzystanie z wtyczki do obsługi obiektów tajnych na Androida. Aby zainstalować wtyczkę i zapisać klucz interfejsu API:

1. W Android Studio otwórz plik build.gradle na poziomie projektu i dodaj poniższy kod do elementu dependencies w sekcji buildscript.

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
   }

2. Następnie otwórz plik build.gradle na poziomie modułu i dodaj do elementu plugins poniższy kod.

   id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
       

3. Zapisz plik i zsynchronizuj projekt z Gradle.
4. Otwórz local.properties w katalogu na poziomie projektu, a potem dodaj poniższy kod. Zastąp YOUR_API_KEY swoim kluczem interfejsu API.

   MAPS_API_KEY=YOUR_API_KEY
       

5. Zapisz plik.
6. W pliku AndroidManifest.xml przejdź do com.google.android.geo.API_KEY i zaktualizuj android:value attribute w ten sposób:

   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="${MAPS_API_KEY}" />
       

Uwaga: jak pokazano powyżej, 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 Map Google na platformie Androida, w tym w pakiecie Maps SDK na Androida. Aby zapewnić zgodność wsteczną, interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ta starsza nazwa umożliwia uwierzytelnianie tylko w interfejsie Android Maps API w wersji 2. Aplikacja może określać tylko jedną nazwę metadanych klucza interfejsu API. Jeśli podasz oba te elementy, interfejs API zgłosi wyjątek.

Spójrz na kod

Sprawdź kod podany w szablonie. Zwróć szczególną uwagę na te pliki w projekcie Android Studio.

Plik aktywności w Mapach

Plik aktywności na mapach stanowi główną aktywność w aplikacji i zawiera kod służący do wyświetlania mapy i zarządzania nią. Domyślnie plik określający aktywność to MapsActivity.java. Jeśli jako język aplikacji ustawisz Kotlin, 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 i widoku mapy. 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. Pierwsze ustawienia, które należy skonfigurować przy dodawaniu mapy, to zwykle lokalizacja mapy i ustawienia kamery, takie jak kąt widzenia, orientacja mapy i poziom powiększenia. Więcej informacji znajdziesz w przewodniku po aparacie i widoku.

• Funkcja addMarker dodaje znacznik do współrzędnych obiektu Sydney. Szczegółowe informacje znajdziesz w przewodniku Markers.

Plik działań na mapach zawiera następujący kod:

Java

import android.os.Bundle;
import androidx.appcompat.app.AppCompatActivity;
import com.google.android.gms.maps.CameraUpdateFactory;
import com.google.android.gms.maps.GoogleMap;
import com.google.android.gms.maps.OnMapReadyCallback;
import com.google.android.gms.maps.SupportMapFragment;
import com.google.android.gms.maps.model.LatLng;
import com.google.android.gms.maps.model.MarkerOptions;

public class MapsActivity extends AppCompatActivity implements OnMapReadyCallback {

    private GoogleMap mMap;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_maps);
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        SupportMapFragment mapFragment = (SupportMapFragment) getSupportFragmentManager()
                .findFragmentById(R.id.map);
        mapFragment.getMapAsync(this);
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     *
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    @Override
    public void onMapReady(GoogleMap googleMap) {
        mMap = googleMap;

        // Add a marker in Sydney and move the camera
        LatLng sydney = new LatLng(-34, 151);
        mMap.addMarker(new MarkerOptions()
                .position(sydney)
                .title("Marker in Sydney"));
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney));
    }
}

      

Kotlin

import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle

import com.google.android.gms.maps.CameraUpdateFactory
import com.google.android.gms.maps.GoogleMap
import com.google.android.gms.maps.OnMapReadyCallback
import com.google.android.gms.maps.SupportMapFragment
import com.google.android.gms.maps.model.LatLng
import com.google.android.gms.maps.model.MarkerOptions

internal class MapsActivity : AppCompatActivity(), OnMapReadyCallback {

    private lateinit var mMap: GoogleMap

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_maps)
        // Obtain the SupportMapFragment and get notified when the map is ready to be used.
        val mapFragment = supportFragmentManager
            .findFragmentById(R.id.map) as SupportMapFragment
        mapFragment.getMapAsync(this)
    }

    /**
     * Manipulates the map once available.
     * This callback is triggered when the map is ready to be used.
     * This is where we can add markers or lines, add listeners or move the camera. In this case,
     * we just add a marker near Sydney, Australia.
     * If Google Play services is not installed on the device, the user will be prompted to install
     * it inside the SupportMapFragment. This method will only be triggered once the user has
     * installed Google Play services and returned to the app.
     */
    override fun onMapReady(googleMap: GoogleMap) {
        mMap = googleMap

        // Add a marker in Sydney and move the camera
        val sydney = LatLng(-34.0, 151.0)
        mMap.addMarker(MarkerOptions()
            .position(sydney)
            .title("Marker in Sydney"))
        mMap.moveCamera(CameraUpdateFactory.newLatLng(sydney))
    }
}

      

Plik Gradle modułu

Plik modułu build.gradle zawiera tę zależność map, która jest wymagana przez pakiet SDK Map Google na Androida.

dependencies {
    implementation 'com.google.android.gms:play-services-maps:18.1.0'
    // ...
}

Uwaga: dokładna wersja może się różnić w zależności od bieżącej wersji pakietu Maps SDK na Androida.

Więcej informacji o zarządzaniu zależność w Mapach znajdziesz w artykule Obsługa wersji.

Plik układu XML

Plik activity_maps.xml jest plikiem 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 zdefiniowana w pliku aktywności mapy.
• 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:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:id="@+id/map"
    tools:context=".MapsActivity"
    android:name="com.google.android.gms.maps.SupportMapFragment" />

Wdrażanie i uruchamianie aplikacji

Po uruchomieniu aplikacji wyświetli się mapa wyśrodkowana na Sydney Australia ze znacznikiem miasta, jak widać na poniższym 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, które jest połączone z komputerem.
   • Możesz też zaznaczyć opcję Uruchom emulator i wybrać skonfigurowane urządzenie wirtualne.
3. Kliknij OK. Android Studio uruchomi Gradle, aby stworzyć aplikację, a następnie wyświetli wyniki na urządzeniu lub w emulatorze. Uruchomienie aplikacji może potrwać kilka minut.

Dalsze kroki

• Konfigurowanie mapy: w tym temacie opisujemy, jak skonfigurować mapy początkowe i czas działania, takie jak położenie kamery, typ mapy, komponenty interfejsu i gesty.

• Dodaj mapę do aplikacji na Androida (Kotlin): to ćwiczenie z programowania przeprowadzi Cię przez aplikację prezentującą kilka dodatkowych funkcji pakietu Maps SDK na Androida.

• Użyj biblioteki KTX Map na Androida: ta biblioteka rozszerzeń Kotlin (KTX) umożliwia korzystanie z kilku funkcji języka Kotlin podczas używania pakietu SDK Map Google na Androida.