Android için Haritalar SDK'sı Hızlı Başlangıç Kılavuzu

Android Studio için Google Haritalar şablonunu kullanarak harita görüntüleyen bir Android uygulaması oluşturun. Ayarlamak istediğiniz mevcut bir Android Studio projeniz varsa Proje Yapılandırması'na bakın.

Bu hızlı başlangıç kılavuzu, Java veya Kotlin ile temel Android geliştirme konusunda bilgi sahibi olan geliştiriciler için hazırlanmıştır.

Geliştirme ortamını ayarlama

  1. Android Studio Arctic Fox veya daha yeni bir sürüm gerekir. Henüz yapmadıysanız indirin ve yükleyin.
  2. Android Studio'da Android Gradle eklentisini 7.0 veya daha yeni bir sürümünü kullandığınızdan emin olun.

Android cihaz kurulumu

Android için Haritalar SDK'sını kullanan bir uygulamayı çalıştırmak istiyorsanız bu uygulamayı, Google API'lerini içeren ve Android 4.0 ya da sonraki bir sürümü temel alan bir Android cihaza ya da Android emülatörüne dağıtmanız gerekir.

  • Android cihaz kullanmak için Uygulamaları donanım cihazında çalıştırma başlıklı makaledeki talimatları uygulayın.
  • Android emülatörü kullanmak için sanal bir cihaz oluşturabilir ve Android Studio ile birlikte gelen Android Virtual Device (AVD) Manager'ı kullanarak emülatörü yükleyebilirsiniz.

Android Studio'da Google Haritalar projesi oluşturma

Android Studio'da Google Haritalar projesi oluşturma prosedürü Flamingo'da ve Android Studio'nun sonraki sürümlerinde değiştirildi. Android Studio'nun kendi sürümünüz için aşağıdaki adımları uyguladığınızdan emin olun.

  1. Android Studio'yu açın ve Android Studio'ya hoş geldiniz penceresinde Yeni Proje Oluştur'u tıklayın.

  2. Yeni Proje penceresindeki Telefon ve Tablet kategorisinde Boş Etkinlik'i seçip İleri'yi tıklayın.

  3. Google Haritalar Etkinliği formunu doldurun:

    • Dil'i Java veya Kotlin olarak ayarlayın. Her iki dil de Android için Haritalar SDK'sı tarafından tam olarak desteklenir. Kotlin hakkında daha fazla bilgi edinmek için Kotlin ile Android uygulamaları geliştirme bölümüne bakın.

    • Minimum SDK'yı, test cihazınızla uyumlu bir SDK sürümüne ayarlayın. Android API düzeyi 19 (Android 4.4, KitKat) veya daha üst bir sürüm olan, Android için Haritalar SDK'sı 18.0.x sürümü için gereken minimum sürümden daha yüksek bir sürüm seçmeniz gerekir. SDK sürümü gereksinimleriyle ilgili en son bilgiler için Sürüm Notları'na bakın.

  4. Son'u tıklayın.

    Android Studio, Gradle'ı başlatır ve projeyi oluşturur. Bu işlem zaman alabilir.

  5. Derleme tamamlandığında Android Studio AndroidManifest.xml ve MapsActivity dosyalarını açar. Etkinliğinizin farklı bir adı olabilir, ancak kurulum sırasında yapılandırdığınız addır.

  6. Google Haritalar Görüntüleme Etkinliği'ni ekleyin:

    1. Google Haritalar Görünüm Etkinliği'ni eklemek istediğiniz paketi sağ tıklayın.
    2. Yeni > Google > Google Haritalar Görüntüleme Etkinliği'ni seçin.

    Haritalar etkinliği ekleyin.

    Daha fazla bilgi için Şablondan kod ekleme bölümüne bakın

  7. AndroidManifest.xml dosyası, bir Google Haritalar API anahtarı alma ve bu anahtarı local.properties dosyanıza ekleme talimatlarını içerir. API anahtarınızı AndroidManifest.xml dosyasına eklemeyin. Bu şekilde API anahtarınız daha az güvenli bir şekilde depolanır. Bunun yerine, bir Cloud projesi oluşturmak ve API anahtarı yapılandırmak için sonraki bölümlerde yer alan talimatları uygulayın.

Google Cloud projenizi oluşturun

Aşağıdaki sekmeleri tıklayarak gerekli Cloud Console kurulum adımlarını tamamlayın:

1. Adım

Konsol

  1. Yeni bir Cloud projesi oluşturmaya başlamak için Google Cloud Console'daki proje seçici sayfasında Proje Oluştur'u tıklayın.

    Proje seçici sayfasına gidin

  2. Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Projeniz için faturalandırmanın etkin olduğunu onaylayın.

    Google Cloud, 0,00 ABD doları tutarında ücretsiz deneme süresi sunar. Deneme süresi, 90 günün sonunda veya hesaba 300 ABD doları tutarında maliyet tahakkuk ettikten sonra (hangisi önce gerçekleşirse) sona erer. Dilediğiniz zaman iptal edebilirsiniz. Google Haritalar Platformu'nda aylık 200 ABD doları değerinde yinelenen bir kredi bulunur. Daha fazla bilgi için Faturalandırma hesabı kredileri ve Faturalandırma bölümlerine bakın.

Google Cloud SDK

gcloud projects create "PROJECT"

Google Cloud SDK, Google Cloud SDK yükleme ve aşağıdaki komutlar hakkında daha fazla bilgi edinin:

2. Adım

Google Haritalar Platformu'nu kullanmak için projenizde kullanmayı planladığınız API'leri veya SDK'ları etkinleştirmeniz gerekir.

Konsol

Android için Haritalar SDK'sını etkinleştirme

Google Cloud SDK

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

Google Cloud SDK, Google Cloud SDK yükleme ve aşağıdaki komutlar hakkında daha fazla bilgi edinin:

3. Adım

Bu adım yalnızca API Anahtarı oluşturma sürecinden geçer. API Anahtarınızı üretim için kullanıyorsanız API anahtarınızı kısıtlamanızı kesinlikle öneririz. Daha fazla bilgiyi ürüne özel API Anahtarlarını Kullanma sayfasında bulabilirsiniz.

API anahtarı, kullanım ve faturalandırma amaçları doğrultusunda projenizle ilişkili isteklerin kimliğini doğrulayan benzersiz bir tanımlayıcıdır. Projenizle ilişkilendirilmiş en az bir API anahtarınız olmalıdır.

API anahtarı oluşturmak için:

Konsol

  1. Google Haritalar Platformu > Kimlik Bilgileri sayfasına gidin.

    Kimlik bilgileri sayfasına gidin

  2. Kimlik bilgileri sayfasında Kimlik bilgileri oluştur > API anahtarı'nı tıklayın.
    API anahtarı oluşturuldu iletişim kutusunda, yeni oluşturduğunuz API anahtarı gösterilir.
  3. Kapat'ı tıklayın.
    Yeni API anahtarı, Kimlik bilgileri sayfasındaki API anahtarları altında listelenir.
    (Üretimde kullanmadan önce API anahtarını kısıtlamayı unutmayın.)

Google Cloud SDK

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

Google Cloud SDK, Google Cloud SDK yükleme ve aşağıdaki komutlar hakkında daha fazla bilgi edinin:

Uygulamanıza API anahtarını ekleyin

Bu bölümde, uygulamanızın güvenli bir şekilde başvuruda bulunabilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize kontrol etmemeniz gerekir. Bu nedenle, projenizin kök dizininde bulunan secrets.properties dosyasında saklamanızı öneririz. secrets.properties dosyası hakkında daha fazla bilgi edinmek için Gradle özellik dosyaları bölümüne bakın.

Bu görevi kolaylaştırmak için Android için Secrets Gradle Plugin'i kullanmanızı öneririz.

Google Haritalar projenize Android için Secrets Gradle Eklentisi'ni yüklemek için:

  1. Android Studio'da proje düzeyindeki build.gradle dosyanızı açın ve aşağıdaki kodu buildscript altındaki dependencies öğesine ekleyin.

    Modern

    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. Modül düzeyindeki build.gradle dosyanızı açıp plugins öğesine aşağıdaki kodu ekleyin.

    Modern

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

    Kotlin

    plugins {
        id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
    }
  3. Dosyayı kaydedin ve projenizi Gradle ile senkronize edin.
  4. Proje düzeyindeki dizininizde secrets.properties dosyasını açın ve ardından aşağıdaki kodu ekleyin. YOUR_API_KEY öğesini API anahtarınızla değiştirin.
    MAPS_API_KEY=YOUR_API_KEY 
  5. Dosyayı kaydedin.
  6. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY bölümüne gidip android:value attribute değerini şu şekilde güncelleyin:
    <meta-data
        android:name="com.google.android.geo.API_KEY"
        android:value="${MAPS_API_KEY}" />
  7. İsteğe bağlı olarak, farklı bir gizli anahtar dosyası veya diğer özellikleri belirtmek için eklentinin özelliklerini düzenleyin. Android Studio'da, proje düzeyindeki build.gradle dosyanızı açın ve secrets özelliğini düzenleyin:

    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.*"
    }

Not: Yukarıda gösterildiği gibi, API anahtarı için önerilen meta veri adı com.google.android.geo.API_KEY'dir. Bu ada sahip bir anahtar, Android için Haritalar SDK'sı dahil olmak üzere Android platformundaki birden fazla Google Haritalar tabanlı API'nin kimliğini doğrulamak için kullanılabilir. API, geriye dönük uyumluluk için com.google.android.maps.v2.API_KEY adını da destekler. Bu eski ad, yalnızca Android Maps API v2 ile kimlik doğrulaması yapılmasına izin verir. Bir uygulama, API anahtarı meta veri adlarından yalnızca birini belirtebilir. Her ikisi de belirtilirse API bir istisna oluşturur.

Koda bakın

Şablon tarafından sağlanan kodu inceleyin. Özellikle Android Studio projenizde aşağıdaki dosyalara bakın.

Haritalar etkinlik dosyası

Haritalar etkinlik dosyası, uygulamanın ana etkinliğidir ve haritayı yönetip görüntülemek için gereken kodu içerir. Varsayılan olarak, etkinliği tanımlayan dosyanın adı MapsActivity.java veya Kotlin'i uygulamanızın dili olarak MapsActivity.kt olarak ayarlarsanız.

Harita etkinliğinin ana öğeleri:

  • SupportMapFragment nesnesi haritanın yaşam döngüsünü yönetir ve uygulama kullanıcı arayüzünün üst öğesidir.

  • GoogleMap nesnesi, harita verilerine ve görünümüne erişim sağlar. Bu, Android için Haritalar SDK'sının ana sınıfıdır. Harita Nesneleri kılavuzu, SupportMapFragment ve GoogleMap nesnelerini daha ayrıntılı olarak açıklar.

  • moveCamera işlevi, haritayı Sidney Avustralya için LatLng koordinatlarında ortalar. Harita eklerken yapılandırılacak ilk ayarlar genellikle harita konumu ve kamera ayarlarıdır (ör. görüntüleme açısı, harita yönü ve yakınlaştırma düzeyi). Ayrıntılar için Kamera ve Görüntüleme kılavuzuna bakın.

  • addMarker işlevi, Sidney'in koordinatlarına bir işaretçi ekler. Ayrıntılar için İşaretçiler kılavuzuna bakın.

Haritalar etkinlik dosyası şu kodu içerir:

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))
    }
}

      

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));
    }
}

      

Modül Gradle dosyası

build.gradle Modül dosyası, Android için Haritalar SDK'sının gerektirdiği aşağıdaki harita bağımlılığını içerir.

dependencies {

    // Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.2.0'
}

Haritalar bağımlılığını yönetme hakkında daha fazla bilgi edinmek için Sürüm oluşturma başlıklı makaleyi inceleyin.

XML düzen dosyası

activity_maps.xml dosyası, uygulamanın kullanıcı arayüzü yapısını tanımlayan XML düzen dosyasıdır. Dosya res/layout dizininde bulunuyor. activity_maps.xml dosyası, aşağıdaki öğeleri içeren bir parça tanımlıyor:

  • tools:context, parçanın varsayılan etkinliğini harita etkinlik dosyasında tanımlanan MapsActivity olarak ayarlar.
  • android:name, parçanın sınıf adını SupportMapFragment olarak ayarlar. Bu, haritalar etkinlik dosyasında kullanılan parça türüdür.

XML düzen dosyası şu kodu içerir:

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

Uygulamayı dağıtma ve çalıştırma

Harita ve işaretçinin Syndney Australia merkezde olduğu ekran görüntüsü.

Uygulamayı başarılı bir şekilde çalıştırdığınızda, merkezde Sidney Avustralya'yı gösteren bir harita görüntülenir ve aşağıdaki ekran görüntüsünde görüldüğü gibi şehirde bir işaretçi bulunur.

Uygulamayı dağıtmak ve çalıştırmak için:

  1. Android Studio'da, uygulamanızı çalıştırmak için Çalıştır menü seçeneğini (veya oynat düğmesi simgesini) tıklayın.
  2. Bir cihaz seçmeniz istendiğinde aşağıdaki seçeneklerden birini belirleyin:
    • Bilgisayarınıza bağlı Android cihazı seçin.
    • Alternatif olarak Emülatörü başlat radyo düğmesini seçin ve ayarladığınız sanal cihazı seçin.
  3. OK (Tamam) seçeneğini tıklayın. Android Studio, uygulamanızı oluşturmak için Gradle'ı başlatır ve ardından sonuçları cihazınızda veya emülatörünüzde görüntüler. Uygulamanın başlatılması birkaç dakika sürebilir.

Sonraki adımlar

  • Harita oluşturma: Bu konuda, haritanız için kamera konumu, harita türü, kullanıcı arayüzü bileşenleri ve hareketler gibi ilk ve çalışma zamanı ayarlarını nasıl yapacağınız açıklanmaktadır.

  • Android uygulamanıza harita ekleyin (Kotlin): Bu codelab, Android için Haritalar SDK'sının bazı ek özelliklerini gösteren bir uygulamada size yol gösterir.

  • Haritalar Android KTX kitaplığını kullanın: Bu Kotlin uzantı (KTX) kitaplığı, Android için Haritalar SDK'sını kullanırken çeşitli Kotlin dil özelliklerinden yararlanmanızı sağlar.