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.

Bu hızlı başlangıç kılavuzu, Kotlin veya Java ile temel Android geliştirmeyi bilen geliştiriciler için hazırlanmıştır.

Geliştirme ortamı hakkında

Bu hızlı başlangıç kılavuzu, Android Studio Hedgehog ve Android Gradle eklentisi 8.2 sürümü kullanılarak geliştirilmiştir.

Not: Geliştirme ortamınızda farklı bir Android Studio veya Gradle 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 için uygulamayı Android 5.0 veya sonraki sürümlere dayalı 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 cihazında çalıştırma başlıklı makaledeki talimatları uygulayın.
• Android emülatörü kullanmak için sanal cihaz oluşturabilir ve Android Studio ile birlikte gelen Android Virtual Device (AVD) Manager'ı kullanarak emülatörü yükleyebilirsiniz.
  Not: Bir Android emülatörü kullanmayı tercih ederseniz Play Store sütununun altında Play simgesi gösterilen bir cihaz seçtiğinizden emin olun. Bu simge, söz konusu profillerin CTS'ye tamamen uygun olduğunu ve Play Store uygulamasını içeren sistem görüntülerini kullanabileceğini gösterir:

  

Android Studio'da Google Haritalar projesi oluşturma

Android Studio'nun Flamingo ve sonraki sürümlerinde Android Studio'da Google Haritalar projesi oluşturma prosedürü değiştirildi.

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çip İleri'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 Maps SDK'nın 19.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 21 ("Lollipop"; Android 5.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 21 ("Lollipop"; Android 5.0)'i seçerseniz uygulamanız Android cihazların% 99'undan fazlasında çalışmalıdır.

   • Build configuration language (Derleme yapılandırma dili) seçeneğini Kotlin DSL veya Groovy DSL olarak ayarlayın. Her iki derleme yapılandırması 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ünümleri 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 seçin.

   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 ad kullanılır.

   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. Bu durumda API anahtarınız daha az güvenli bir şekilde saklanır. Bunun yerine, Cloud projesi oluşturmak ve API anahtarı yapılandırmak için Google Cloud projenizi ayarlama bölümündeki talimatları uygulayın.

Google Cloud projenizi oluşturma

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 gitme

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ı değerinde ücret biriktikten sonra (hangisi önce gerçekleşirse) sona erer. Dilediğ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ı düşünmüyorsanız mevcut projeyi seçmek yerine yeni bir proje oluşturun. Alıştırmayı tamamladıktan sonra projeyi silerek 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ükleme 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 süreci ele alını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ş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 gitme

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ükleme 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 kontrol sisteminize işlememeniz gerekir. Bu nedenle, anahtarınızı projenizin kök dizininde bulunan secrets.properties dosyasına kaydetmenizi öneririz. secrets.properties dosyası hakkında daha fazla bilgi için Gradle özellik dosyaları konusuna bakın.

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

Not: En yeni sistem gereksinimleri ve yükleme talimatları için GitHub'daki Android İçin Secrets Gradle Plugin belgelerine bakın.

Google Haritalar projenize Android İçin Secrets Gradle Plugin'i yüklemek üzere:

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

   Kotlin

   buildscript {
       dependencies {
           classpath("com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1")
       }
   }

   Modern

   buildscript {
       dependencies {
           classpath "com.google.android.libraries.mapsplatform.secrets-gradle-plugin:secrets-gradle-plugin:2.0.1"
       }
   }

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

   Kotlin

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

   Modern

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

3. Modül düzeyindeki build.gradle.kts veya build.gradle dosyanızda targetSdk ve compileSdk değerlerinin 34 olarak ayarlandığından emin olun.
4. Projenizi Gradle ile senkronize edin.
5. 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. secrets.properties, sürüm kontrol sistemine dahil edilmediği için anahtarınızı bu dosyada saklayın.
   Not: secrets.properties dosyası yoksa local.properties dosyasıyla aynı klasörde oluşturun.

   MAPS_API_KEY=YOUR_API_KEY

6. Ü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 API anahtarı için yedek bir konum sağlamaktır. Böylece derlemeler başarısız olmaz. Bu durum, secrets.properties öğesini atlayan bir sürüm kontrol sisteminden uygulamayı klonlarsanız ve API anahtarınızı sağlamak için henüz yerel olarak bir secrets.properties dosyası oluşturmadıysanız meydana gelebilir.

7. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY bölümüne gidin ve android:value attribute değerini güncelleyin. <meta-data> etiketi yoksa <application> etiketinin alt öğesi olarak oluşturun.

   <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 platformundaki Android için Haritalar SDK'sı da dahil olmak üzere birden fazla Google Haritalar tabanlı API'de kimlik doğrulaması yapmak 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 bir istisna oluşturur.

8. Android Studio'da modül düzeyindeki build.gradle.kts veya build.gradle dosyanızı açın ve 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 ve diğer özellikleri ayarlayın.

   Kotlin

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

Koda bakma

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

Haritalar Etkinliği dosyası

Haritalar etkinlik dosyası, uygulamanın ana etkinliğidir ve haritayı yönetip görüntülemeye yönelik 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üme 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ı bir şekilde açıklanmaktadır.

• moveCamera işlevi, haritayı Avustralya'nın Sidney şehrine ait 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ünüm 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.

Modül Gradle dosyası

build.gradle.kts modülü dosyası, Android için Haritalar SDK'sı tarafından gerekli olan aşağıdaki Haritalar bağımlılığını içeriyor.

dependencies {

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

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 etkinlik dosyasında tanımlanan MapsActivity olarak ayarlar.
• android:name, parçanın sınıf adını, haritalar etkinliği dosyasında kullanılan parça türü olan SupportMapFragment olarak ayarlar.

XML düzen dosyasında aşağıdaki kod bulunur:

<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, aşağıdaki ekran görüntüsünde gösterildiği gibi, Avustralya'nın Sidney şehrine odaklanmış ve şehirde bir işaretçi bulunan bir harita gösterilir.

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

1. Uygulamanızı çalıştırmak için Android Studio'da Run (Çalıştır) menü seçeneğini (veya oynatma 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çip ayarladığınız sanal cihazı belirleyin.
3. Tamam'ı tıklayın. Android Studio, uygulamanızı oluşturmak için Gradle'ı başlatır ve 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 belgede, 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 ayarlanacağı 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 adım adım açıklanıyor.

• Maps 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ızı sağlar.