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

Android Studio için Google Haritalar Görünümleri şablonunu kullanarak harita gösteren bir Android uygulaması oluşturun. Kurmak istediğiniz mevcut bir Android Studio projeniz varsa Android Studio projesi oluşturma başlıklı makaleyi inceleyin.

Not: Bu hızlı başlangıç kılavuzunda, SupportMapFragment ile bir XML düzeni oluşturan Google Haritalar Görünümleri Etkinliği şablonu kullanılır. Kullanıcı arayüzünüzü Jetpack Compose ile oluşturuyorsanız bunun yerine Haritalar Compose kitaplığına bakın.

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

Geliştirme ortamı hakkında

Android Studio ve Android Gradle eklentisinin en son kararlı sürümünü kullanmanızı öneririz.

Not: Geliştirme ortamınızda Android Studio veya Gradle'ın farklı bir sürümü kullanılıyorsa adımları ortamınıza göre değiştirmeniz gerekebilir. Android Studio ve Gradle sürümleri hakkında daha fazla bilgi için Android Gradle eklentisi ve Android Studio uyumluluğu başlıklı makaleyi inceleyin.

Android cihaz kurma

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

• Android cihaz kullanmak için Uygulamaları donanım cihazda çalıştırma bölümündeki talimatları uygulayın.
• Android emülatörü kullanmak için sanal cihaz oluşturabilir ve Android Studio ile birlikte gelen Cihaz Yönetim Paneli'ni kullanarak emülatörü yükleyebilirsiniz.
  Not: Android emülatörü kullanmayı tercih ederseniz Play sütununda Google Play simgesinin () gösterildiği bir cihaz profili seçtiğinizden emin olun. Bu simge, bu profillerin CTS ile tam uyumlu olduğunu ve Play Store uygulamasını içeren sistem görüntülerini kullanabileceğini gösterir:

  

  Android Studio Cihaz Yöneticisi'ndeki Cihaz Ekle iletişim kutusunda, Play sütununda Google Play simgesi bulunan sanal cihaz profilleri gösterilir.

Android Studio'da Google Haritalar projesi oluşturma

1. Android Studio'yu açın ve Android Studio'ya Hoş Geldiniz penceresinde Yeni Proje'yi tıklayın.

2. New Project (Yeni Proje) penceresinde, Phone and Tablet (Telefon ve Tablet) kategorisi altında No Activity'yi (Etkinlik Yok) seçin ve Next'i (İleri) tıklayın.

   Not: No Activity (Etkinlik Yok) yerine varsayılan Empty Activity (Boş Etkinlik) (Jetpack Compose) şablonuyla başlayıp daha sonra Google Maps Views Activity (Google Haritalar Görünüm Etkinliği) eklerseniz MapsActivity (AppCompatActivity), Compose şablonu res/values/themes.xml içindeki tema üst öğesini android:Theme.Material.Light.NoActionBar olarak ayarladığından başlatma sırasında IllegalStateException: You need to use a Theme.AppCompat theme (or descendant) with this activity ile kilitlenir. Bu kilitlenmeyi önlemek için temanızın res/values/themes.xml içindeki parent değerini Theme.AppCompat.DayNight.NoActionBar olarak güncelleyin ve .MapsActivity öğesinin AndroidManifest.xml içinde MAIN/LAUNCHER etkinliği olarak yapılandırıldığından emin olun.

3. Yeni Proje formunu doldurun:

   • Language'ı (Dil) 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 başlıklı makaleyi inceleyin.

   • Minimum SDK'yı test cihazınızla uyumlu bir SDK sürümüne ayarlayın. Android için Haritalar SDK'sının 20.0.x sürümü tarafından gerekli olan minimum sürümden daha yüksek bir sürüm seçmeniz gerekir. Bu sürüm, Android API düzeyi 23 ("Marshmallow"; Android 6.0) veya sonraki sürümlerdir. SDK sürümü şartlarıyla ilgili en son bilgiler için Sürüm Notları'na bakın.

     Not: Hangi SDK sürümünü seçeceğinizden emin değilseniz desteklenen Android SDK'larının dağıtım bilgilerini görüntülemek için Seçim yapmama yardımcı ol bağlantısını seçin. Örneğin, Android API düzeyi 23 ("Marshmallow"; Android 6.0)'ü seçerseniz uygulamanız Android cihazların% 99'undan fazlasında çalışır.

   • Derleme yapılandırması dili'ni Kotlin DSL veya Groovy DSL olarak ayarlayın. Her iki derleme yapılandırması dili için snippet'ler aşağıdaki prosedürlerde gösterilmiştir.

4. Son'u tıklayın.

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

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

   1. Projenizdeki app klasörünü sağ tıklayın.

   2. Yeni > Google > Google Haritalar Görüntüleme Etkinliği'ni seçin:

      

      Android Studio'da app bağlam menüsünden Google Haritalar Görünümleri Etkinliği ekleme.

   3. New Android Activity (Yeni Android Etkinliği) iletişim kutusunda Launcher Activity (Başlatıcı Etkinliği) onay kutusunu işaretleyin.

   4. Son'u seçin.

      Daha fazla bilgi için Şablondan kod ekleme başlıklı makaleyi inceleyin.

6. Derleme tamamlandığında Android Studio, AndroidManifest.xml ve MapsActivity dosyalarını açar. Etkinliğiniz, kurulum sırasında yaptığınız yapılandırmaya bağlı olarak farklı bir ada sahip olabilir.

   Dikkat: Google Haritalar Görünüm Etkinliği şablonu tarafından oluşturulan proje, ek yapılandırma olmadan çalışmaz. Şablon, Android için Secrets Gradle Plugin'i libs.versions.toml ve build.gradle.kts dosyalarına eklese de secrets.properties dosyasını yapılandırmaz. Bunun yerine, doğrudan AndroidManifest.xml dosyasına bir YOUR_API_KEY yer tutucusu yerleştirir (local.properties dosyasına referans veren eski yorumlarla birlikte). API anahtarınızı doğrudan AndroidManifest.xml dosyasına yapıştırmayın veya local.properties dosyasına eklemeyin. Bunun yerine, MAPS_API_KEY değerini bir secrets.properties dosyasına kaydetmek, modül düzeyindeki Gradle dosyanızda secrets bloğunu yapılandırmak ve AndroidManifest.xml içinde android:value="${MAPS_API_KEY}" değerini ayarlamak için Google Cloud projenizi ayarlama ve API anahtarını uygulamanıza ekleme bölümlerindeki talimatları uygulayın.

Google Cloud projenizi ayarlama

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

1. Adım

Konsol

1. Google Cloud Console'daki proje seçici sayfasında, yeni bir Cloud projesi oluşturmaya başlamak için 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 etkinleştirildiğini onaylayın.

   Google Cloud, ücretsiz deneme sürümü sunar. Deneme süresi, 90 günün sonunda veya hesapta 300 ABD doları tutarında ücret tahakkuk ettiğinde (hangisi önce gerçekleşirse) sona erer. İstediğiniz zaman iptal edebilirsiniz. Daha fazla bilgi için Faturalandırma hesabı kredileri ve Faturalandırma başlıklı makaleleri inceleyin.

Google Cloud SDK

gcloud projects create "PROJECT"

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

• gcloud projects create

Not: Bir öğrenme alıştırmasında oluşturduğunuz kaynakları saklamayı planlamıyorsanız mevcut bir projeyi seçmek yerine yeni bir proje oluşturun. Alıştırmayı tamamladıktan sonra projeyi silebilir ve projeyle ilişkili tüm kaynakları kaldırabilirsiniz.

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, Cloud SDK yüklemesi ve aşağıdaki komutlar hakkında daha fazla bilgi edinin:

• gcloud services enable
• gcloud services disable

3. Adım

Bu adımda yalnızca API anahtarı oluşturma işlemi açıklanmaktadır. API anahtarınızı üretimde kullanıyorsanız API anahtarınızı kısıtlamanızı önemle tavsiye ederiz. Ürüne özel API Anahtarlarını Kullanma sayfasında daha fazla bilgi bulabilirsiniz.

API anahtarı, kullanım ve faturalandırma amacıyla projenizle ilişkili isteklerin kimliğini doğrulayan benzersiz bir tanımlayıcıdır. Projenizle ilişkili 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ı bölümünde listelenir.
   (Üretimde kullanmadan önce API anahtarını kısıtlamayı unutmayın.)

Google Cloud SDK

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

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

• gcloud services api-keys create

API anahtarını uygulamanıza ekleme

Bu bölümde, API anahtarınızın uygulamanız tarafından güvenli bir şekilde referans alınabilmesi için nasıl saklanacağı açıklanmaktadır. API anahtarınızı sürüm denetim sisteminize işlememeniz gerekir. Bu nedenle, anahtarınızı projenizin kök dizininde bulunan secrets.properties dosyasına kaydetmenizi ve bu dosyayı sürüm denetiminin dışında tutmanızı öneririz. Gradle özellik dosyaları hakkında daha fazla bilgi için Gradle özellik dosyaları konusuna bakın.

Bu görevi basitleştirmek için Android için Secrets Gradle Plugin'i kullanmanızı öneririz.

Android için Secrets Gradle Eklentisi'ni yüklemek ve API anahtarınızı depolamak için:

1. Android Studio'da üst düzey build.gradle.kts veya build.gradle dosyanızı açın ve aşağıdaki kodu plugins bloğuna ekleyin.

   Kotlin

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

   Modern

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

2. Modül düzeyindeki build.gradle.kts veya build.gradle dosyanızı açın ve aşağıdaki kodu plugins öğesine ekleyin.

   Kotlin

   plugins {
       id("com.android.application")
       // ...
       id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
   }

   Modern

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

3. Android Studio kullanıyorsanız projenizi Gradle ile senkronize edin.
4. En üst düzey dizininizde secrets.properties dosyasını açın ve aşağıdaki kodu ekleyin. YOUR_API_KEY kısmını API anahtarınızla değiştirin. API anahtarınızı sürüm denetimine eklememek için secrets.properties dosyanıza .gitignore eklediğinizden (veya sürüm denetim sisteminizden hariç tuttuğunuzdan) emin olun.
   Not: secrets.properties dosyası yoksa local.properties dosyasıyla aynı klasörde oluşturun.

   MAPS_API_KEY=YOUR_API_KEY

5. En üst düzey dizininizde, secrets.properties dosyasıyla aynı klasörde local.defaults.properties dosyasını oluşturun ve aşağıdaki kodu ekleyin.

   Not: Kodu gösterildiği şekilde girin. DEFAULT_API_KEY kısmını API anahtarınızla değiştirmeyin.

   MAPS_API_KEY=DEFAULT_API_KEY

   Bu dosyanın amacı, secrets.properties dosyası bulunamazsa derlemelerin başarısız olmaması için API anahtarına yedek bir konum sağlamaktır. Bu durum, uygulamayı secrets.properties dosyasını atlayan bir sürüm denetim sisteminden klonladıysanız ve API anahtarınızı sağlamak için yerel olarak bir secrets.properties dosyası oluşturmadıysanız ortaya çıkabilir.

6. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY bölümüne gidin ve android:value özelliğini aşağıdaki gibi güncelleyin:

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

   Not: com.google.android.geo.API_KEY, API anahtarı için önerilen meta veri adıdır. Bu ada sahip bir anahtar, Android platformunda Android için Haritalar SDK'sı da dahil olmak üzere Google Haritalar tabanlı birden fazla 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'de kimlik doğrulamaya izin verir. Bir uygulama, API anahtarı meta veri adlarından yalnızca birini belirtebilir. Her ikisi de belirtilirse API bir istisna oluşturur.

7. Android Studio'da modül düzeyindeki build.gradle.kts veya build.gradle dosyanızı açıp secrets özelliğini düzenleyin. secrets özelliği yoksa ekleyin.

   Eklentinin özelliklerini düzenleyerek propertiesFileName değerini "secrets.properties", defaultPropertiesFileName değerini "local.defaults.properties" olarak ayarlayın ve diğer özellikleri belirleyin.

   Kotlin

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
   }

   Modern

   secrets {
       // To add your Maps API key to this project:
       // 1. If the secrets.properties file does not exist, create it in the root directory (the same folder as the root 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"
   }

Not: Logcat E/Google Maps Android API: Authorization failure hatası bildirirse veya harita parçaları yüklenemezse Google Cloud projenizde Android için Haritalar SDK'sı'nın etkinleştirildiğini, birleştirilmiş AndroidManifest.xml dosyanızdaki API anahtarının geçerli olduğunu ve API anahtarınız Android uygulama kısıtlamaları kullanıyorsa projenizin paket adının (ör. com.example.myfirstmapsapp) ve imzalama anahtar deponuzun SHA-1 parmak izinin (ör. ~/.android/debug.keystore) Google Cloud'da API anahtarının izin verilen Android uygulamalarına eklendiğini doğrulayın.

Koda bakın

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

Haritalar etkinlik dosyası

Harita etkinliği 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 dosya MapsActivity.java olarak adlandırılır. Uygulamanızın dilini Kotlin olarak ayarladıysanız bu dosya MapsActivity.kt olarak adlandırılır.

Haritalar etkinliğinin ana öğeleri:

• SupportMapFragment nesnesi, haritanın yaşam döngüsünü yönetir ve uygulamanın 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ılavuzunda SupportMapFragment ve GoogleMap nesneleri daha ayrıntılı olarak açıklanmaktadır.

• moveCamera işlevi, haritayı Avustralya'nın Sidney şehrinin 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 seviyesi). Ayrıntılar için Kamera ve Görünüm kılavuzuna bakın.

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

Kotlin

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

      

Java

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

      

Modül Gradle dosyası

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

Kotlin

dependencies {

    // Maps SDK for Android
    implementation(libs.play.services.maps)
}

Modern

dependencies {

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

Projeniz bir Gradle sürüm kataloğu (gradle/libs.versions.toml) kullanıyorsa libs.versions.toml içinde play-services-maps bağımlılığını tanımlayın:

[versions]
play-services-maps = "20.0.0"

[libraries]
play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }

Not: Tam sürüm, Android için Haritalar SDK'sının mevcut sürümüne göre değişebilir.

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ünün yapısını tanımlayan XML düzen dosyasıdır. Dosya, res/layout dizininde bulunur. activity_maps.xml dosyası, aşağıdaki öğeleri içeren bir parçayı bildirir:

• 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ı harita etkinliği dosyasında kullanılan parça türü olan SupportMapFragment olarak ayarlar.

XML düzen dosyası aşağıdaki kodu içerir:

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

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

Uygulamayı başarıyla çalıştırdığınızda, ekran görüntüsünde gösterildiği gibi, Avustralya'nın Sidney şehrini merkeze alan ve şehir üzerinde bir işaretçi bulunan bir harita görüntülenir.

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

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

Sonraki adımlar

• Harita oluşturma: Bu dokümanda, haritanızın ilk ve çalışma zamanı ayarlarının (ör. kamera konumu, harita türü, kullanıcı arayüzü bileşenleri ve hareketler) nasıl yapılacağı açıklanmaktadır.

• Android uygulamanıza harita ekleme (Kotlin): Bu codelab'de, Android için Haritalar SDK'sının bazı ek özelliklerini gösteren bir uygulama hakkında bilgi edineceksiniz.

• Haritalar Android KTX kitaplığını kullanın: Bu Kotlin uzantıları (KTX) kitaplığı, Android için Haritalar SDK'sını kullanırken çeşitli Kotlin dili özelliklerinden yararlanmanıza olanak tanır.