Pakiet SDK Map na Androida – krótkie wprowadzenie

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Utwórz aplikację na Androida, która wyświetli mapę, korzystając z szablonu Map Google na Androida Studio. Jeśli masz już projekt Android Studio, który chcesz skonfigurować, przeczytaj Konfigurację projektu.

Ten krótki przewodnik jest przeznaczony dla deweloperów, którzy znają podstawy programowania na Androidzie w języku Java lub Kotlin.

Skonfiguruj środowisko programistyczne

  1. Wymagany jest Android Studio Arctic Fox lub nowszy. Pobierz i zainstaluj, jeśli jeszcze jej nie masz.
  2. Upewnij się, że używasz wtyczki Android Gradle w wersji 7.0 lub nowszej w Android Studio.

Konfigurowanie urządzenia z Androidem

Aby uruchomić aplikację, która korzysta z pakietu SDK Map na Androida, musisz ją wdrożyć na urządzeniu z Androidem lub w emulatorze Androida opartym na Androidzie 4.0 lub nowszym i interfejsach API Google.

Tworzenie projektu Map Google w 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 Aktywność w Mapach Google i kliknij Dalej.

  3. Wypełnij formularz Aktywności w Mapach Google.

    • Ustaw Język na Java lub Kotlin. Pakiet SDK Map na Androida w pełni obsługuje oba języki. Aby dowiedzieć się więcej o Kotlinie, przeczytaj artykuł o tworzeniu aplikacji na Androida na platformie Kotlin.

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

  4. Kliknij Zakończ

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

  5. Gdy kompilacja się zakończy, Android Studio otwiera pliki AndroidManifest.xml i MapsActivity. Twoja aktywność może mieć inną nazwę, ale będzie to ta, która została przez Ciebie skonfigurowana podczas konfiguracji.

  6. Plik AndroidManifest.xml zawiera instrukcje, jak uzyskać klucz interfejsu API Map Google, a następnie dodać go do pliku local.property. Nie dodawaj klucza interfejsu API do pliku AndroidManifest.xml. W ten sposób Twój klucz API jest bezpieczniejszy. Zamiast tego wykonaj czynności opisane w kolejnych sekcjach, aby utworzyć projekt Cloud i skonfigurować klucz interfejsu API.

Skonfiguruj w Cloud Console

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

Krok 1

Konsola

  1. W konsoli Google Cloud na stronie wyboru projektu kliknij Utwórz projekt, aby zacząć tworzyć nowy projekt Cloud.

    Otwórz stronę selektora projektów

  2. Sprawdź, czy w projekcie Cloud włączone są płatności. Upewnij się, że płatności w Twoim projekcie są włączone.

    W ramach okresu próbnego Google Cloud może być 0,00 USD. Okres próbny kończy się po 90 dniach lub po naliczeniu opłat na kwotę 300 USD, w zależności od tego, co nastąpi wcześniej. W każdej chwili możesz zrezygnować. Google Maps Platform oferuje cykliczną kwotę w wysokości 200 USD miesięcznie. Więcej informacji znajdziesz w artykułach Środki na koncie rozliczeniowym i Płatności.

(pakiet) SDK Cloud

gcloud projects create "PROJECT"

Dowiedz się więcej o pakiecie SDK Google Cloud, instalowaniu pakietu SDK Cloud i o tych poleceniach:

Krok 2

Aby korzystać z Google Maps Platform, musisz włączyć interfejsy API lub pakiety SDK, których zamierzasz użyć w projekcie.

Konsola

Włączanie pakietu SDK Map na Androida

(pakiet) SDK Cloud

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

Dowiedz się więcej o pakiecie SDK Google Cloud, instalowaniu pakietu SDK Cloud i o tych poleceniach:

Krok 3

Ten krok obejmuje tylko proces tworzenia klucza interfejsu API. Jeśli używasz klucza interfejsu API w środowisku produkcyjnym, zdecydowanie warto ograniczyć jego klucz. Więcej informacji znajdziesz na stronie Używanie kluczy interfejsu API danej usługi.

Klucz interfejsu API to unikalny identyfikator uwierzytelniający żądania powiązane z Twoim projektem do celów rozliczeniowych i użytkowania. Z Twoim projektem musi być powiązany co najmniej jeden klucz interfejsu API.

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 API wyświetla 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ć używanie klucza interfejsu API przed jego użyciem w środowisku produkcyjnym).

(pakiet) SDK Cloud

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

Dowiedz się więcej o pakiecie SDK Google Cloud, instalowaniu pakietu SDK Cloud i o tych poleceniach:

Dodaj klucz interfejsu API do swojej aplikacji

W tej sekcji dowiesz się, jak przechowywać klucz interfejsu API, aby można było bezpiecznie odwoływać się do niego przez aplikację. Zalecamy niesprawdzanie klucza interfejsu API w systemie kontroli wersji, dlatego zalecamy przechowywanie 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 uprościć to zadanie, zalecamy użycie wtyczki Gradle 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 ten 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 ten kod do elementu plugins.
    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 i dodaj ten kod. Zastąp YOUR_API_KEY kluczem interfejsu API.
    MAPS_API_KEY=YOUR_API_KEY
        
  5. Zapisz plik.
  6. W pliku AndroidManifest.xml otwórz stronę 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 opartych na Mapach Google na platformie Android, w tym również w pakiecie Maps SDK na Androida. Aby zapewnić zgodność wsteczną, interfejs API obsługuje też nazwę com.google.android.maps.v2.API_KEY. Ta nazwa starszego typu umożliwia uwierzytelnianie tylko dla interfejsu Android Maps API v2. Aplikacja może określać tylko jedną z nazw metadanych klucza interfejsu API. Jeśli podasz obie opcje, interfejs API zwróci wyjątek.

Zobacz kod

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

Plik aktywności Map Google

Plik aktywności z mapami jest główną aktywnością aplikacji i zawiera kod do zarządzania mapą i jej wyświetlania. Domyślnie plik definiujący aktywność ma nazwę MapsActivity.java lub jeśli dla Twojej aplikacji ustawiony jest język Kotlin (MapsActivity.kt).

Główne 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 SDK Map na Androida. Przewodnik Obiekty mapy zawiera szczegółowy opis obiektów SupportMapFragment i GoogleMap.

  • Funkcja moveCamera wyśrodkowuje mapę na współrzędnych LatLng w Sydney Australia. Pierwszymi ustawieniami, które należy skonfigurować podczas dodawania mapy, są zwykle lokalizacja i ustawienia kamery, takie jak kąt patrzenia, orientacja mapy i poziom powiększenia. Szczegółowe informacje znajdziesz w przewodniku po aparacie i widoku.

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

Plik aktywności map zawiera ten 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ł build.gradle zawiera tę zależność map, która jest wymagana przez pakiet SDK Map na Androida.

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

Aby dowiedzieć się więcej o zarządzaniu zależnościami w Mapach, przeczytaj Informacje o wersji.

Plik układu XML

Plik activity_maps.xml to plik układu XML, który definiuje strukturę interfejsu aplikacji. Plik znajduje się w katalogu res/layout. Plik activity_maps.xml deklaruje fragment, który zawiera następujące elementy:

  • tools:context ustawia domyślną aktywność tego fragmentu na MapsActivity, który jest zdefiniowany w pliku aktywności map.
  • android:name ustawia nazwę klasy fragmentu na SupportMapFragment, czyli typ segmentu 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: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

Zrzut ekranu z mapą i znacznikiem wyśrodkowanym na Syndney Australia.

Po uruchomieniu aplikacji wyświetli się mapa wyśrodkowana na Sydney Australia ze znacznikiem miasta, tak jak na tym zrzucie ekranu.

Aby wdrożyć i uruchomić aplikację:

  1. W Android Studio kliknij opcję 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 połączone z komputerem.
    • Możesz też zaznaczyć opcję Uruchom emulator i wybrać skonfigurowane urządzenie wirtualne.
  3. Kliknij OK. Android Studio uruchomi Gradle w celu skompilowania aplikacji, a następnie wyświetli wyniki na urządzeniu lub w emulatorze. Może minąć kilka minut, zanim aplikacja zostanie uruchomiona.

Dalsze kroki