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'nun 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 Store sütununda Play simgesi gösterilen bir cihaz profili seçtiğinizden emin olun. Bu simge, bu profillerin CTS ile tam uyumlu olduğunu ve Google Play Store uygulamasını içeren sistem görüntülerini kullanabileceğini gösterir.

Android Studio'da Google Haritalar projesi oluşturma

1. Android Studio'yu açın ve Welcome to Android Studio (Android Studio'ya Hoş Geldiniz) penceresinde New Project'i (Yeni Proje) tıklayın.

2. Yeni Proje penceresindeki Telefon ve Tablet kategorisinde Etkinlik Yok'u seçin ve Sonraki'yi tıklayın.

3. Yeni Proje formunu doldurun:

   • Language (Dil) seçeneğini 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ırma diline ait snippet'ler aşağıdaki prosedürlerde gösterilmektedir.

4. Son'u tıklayın.

   Android Studio, Gradle'ı başlatır ve projeyi oluşturur. 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.

      

   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 işlemi tamamlandığında Android Studio, AndroidManifest.xml ve MapsActivity dosyalarını açar. Etkinliğinizin adı farklı olabilir ancak kurulum sırasında yapılandırdığınız etkinliktir.

   Dikkat: AndroidManifest.xml dosyası, Google Haritalar API anahtarı alma ve ardından bu anahtarı local.properties dosyanıza ekleme talimatlarını içerir. API anahtarınızı local.properties dosyasına eklemeyin. Bunun yerine, API anahtarınızı Android için Secrets Gradle eklentisini kullanarak ayrı bir secrets.properties dosyasına kaydetmek üzere Google Cloud projenizi oluşturma ve API anahtarını uygulamanıza ekleme bölümündeki 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, 0,00 ABD doları tutarında bir deneme ücreti sunar. Deneme süresi, 90 günün sonunda veya hesapta 300 ABD doları tutarında ücret biriktikten sonra (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ükleme 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ı kesinlikle öneririz. Daha fazla bilgiyi ürüne özel API Anahtarlarını Kullanma sayfasında 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 işlememek için secrets.properties dosyasını .gitignore dosyanıza eklediğinizden (veya başka bir şekilde 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: API anahtarı için önerilen meta veri adı com.google.android.geo.API_KEY'dir. 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ğrulamasına izin verir. Bir uygulama yalnızca API anahtarı meta veri adlarından birini belirtebilir. Her ikisi de belirtilirse API 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 raporu veriyorsa Google Cloud projenizde Android için Haritalar SDK'sı'nın etkinleştirildiğini ve birleştirilmiş AndroidManifest.xml dosyanızdaki API anahtarının geçerli olduğunu doğrulayın.

Koda bakın

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

Haritalar Etkinliği dosyası

Harita etkinliği dosyası, uygulamanın ana etkinliğidir ve haritayı yönetip görüntülemek için gereken kodu içerir. Etkinliği tanımlayan dosya varsayılan olarak MapsActivity.java veya uygulamanızın dili olarak Kotlin'i ayarlarsanız MapsActivity.kt olarak adlandırılır.

Haritalar etkinliğinin ana unsurları:

• 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 rehberinde 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çeriyor.

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

Projenizde Gradle sürüm kataloğu (gradle/libs.versions.toml) kullanılıyorsa play-services-maps bağımlılığını libs.versions.toml içinde 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 bağlı olarak 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ça bildirir:

• tools:context, parçanın varsayılan etkinliğini, haritalar etkinliği 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 şehrinde ortalanmış ve şehirde bir işaretçi bulunan bir harita gösterilir.

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

1. Android Studio'da Run (Çalıştır) menü seçeneğini (veya oynatma düğmesi simgesini) tıklayarak uygulamanızı çalıştırı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ı oluşturmak 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.

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