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ştirme konusunda bilgi sahibi olan Android geliştiricileri 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 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 için uygulamayı Android 6.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 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 Android Sanal Cihazı (AVD) Yöneticisi'ni kullanarak emülatörü yükleyebilirsiniz.
  Not: Android emülatörü kullanmayı tercih ederseniz Play Store sütununda Play simgesi () bulunan bir cihaz seçtiğinizden emin olun. Bu simge, söz konusu profillerin CTS ile tamamen uyumlu 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'da Google Haritalar projesi oluşturma prosedürü, Android Studio'nun Flamingo ve sonraki sürümlerinde değiştirildi.

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.

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.

   • 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ı 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 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. Yeni Android Etkinliği iletişim kutusunda 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 ad geçerlidir.

   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, Google Cloud projenizi oluşturma bölümündeki talimatları uygulayarak bir Cloud projesi oluşturun ve API anahtarı yapılandırı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 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ı 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ü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ü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. Ü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ş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ı 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 denetim 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 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 kök düzeyindeki build.gradle dosyanızı açın ve buildscript altındaki dependencies öğesine aşağıdaki kodu 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. Uygulama düzeyindeki build.gradle dosyanızı açın ve aşağıdaki kodu plugins öğesine ekleyin.

   Modern

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

   Kotlin

   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. Proje düzeyindeki dizininizde local.properties dosyasını açın ve aşağıdaki kodu ekleyin. YOUR_API_KEY kısmını API anahtarınızla değiştirin.

   MAPS_API_KEY=YOUR_API_KEY

5. 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 platformundaki Android için Haritalar SDK'sı da dahil olmak üzere Google Haritalar tabanlı birden fazla 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ğrulamaya izin verir. Bir uygulama, API anahtarı meta veri adlarından yalnızca birini belirtebilir. Her ikisi de belirtilirse API istisna oluşturur.

Koda bakın

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

Haritalar etkinlik dosyası

Haritalar etkinlik dosyası, uygulamanın ana etkinliğidir ve haritayı yönetip görüntülemeye yarayan 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 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 kılavuzunda SupportMapFragment ve GoogleMap nesneleri daha ayrıntılı bir şekilde açıklanmaktadır.

• moveCamera işlevi, haritayı Sidney, Avustralya'nın LatLng koordinatlarında ortalar. Harita eklerken yapılandırılacak ilk ayarlar genellikle harita konumu ve kamera ayarlarıdır (ör. görüş 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.

Modül Gradle dosyası

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

dependencies {

    // Maps SDK for Android
    implementation(libs.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ça 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ı SupportMapFragment olarak ayarlar. Bu, haritalar etkinliği dosyasında kullanılan parça türüdür.

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, aşağıdaki ekran görüntüsünde gösterildiği gibi, Sidney (Avustralya) merkezli ve şehir üzerinde bir işaretçi bulunan bir harita gösterilir.

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ı 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, Android için Haritalar SDK'sının bazı ek özelliklerini gösteren bir uygulama hakkında size yol gösterir.

• 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.