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örüntüleyen bir Android uygulaması oluşturun. Oluşturmak 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 hakkında bilgi sahibi olan 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 Android Studio veya Gradle'in farklı bir sürümü kullanılıyorsa adımları ortamınıza göre değiştirmeniz gerekebilir. Daha fazla Android Studio ve Gradle sürümleri hakkında bilgi edinmek için Android Gradle eklentisine bakın. ve Android Studio dikkat edin.

Android cihaz kurma

Android için Haritalar SDK'sını kullanan bir uygulamayı çalıştırmak istiyorsanız uygulamayı Android 5.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 cihazında çalıştırma başlıklı makaledeki talimatları uygulayın.
• Android emülatörünü kullanmak için Android Studio ile birlikte gelen Android Virtual Device (AVD) Manager'ı kullanarak sanal cihaz oluşturabilir ve emülatörü yükleyebilirsiniz.
  Not: Android emülatörü kullanmayı seçerseniz Play Store sütununun altında görüntülenen Oynat simgesi olan bir cihaz seçersiniz. Bu simge, bu profillerin tamamen CTS uyumlu olduğunu ve Play Store uygulamasını içeren sistem resimlerini kullanabileceğini gösterir:

  

Android Studio'da Google Haritalar projesi oluşturma

Android Studio'da Google Haritalar projesi oluşturma prosedürü ve Android Studio'nun sonraki sürümleri.

1. Android Studio'yu açın ve şurada Yeni Proje'yi tıklayın: Android Studio'ya hoş geldiniz penceresi.

2. Yeni Proje penceresinde, Telefon ve Tablet kategorisinde, Etkinlik Yok'u seçin ve İleri'yi tıklayın.

3. Yeni Proje 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 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ı 19.0.x sürümü tarafından gereken minimum sürümden (Android API düzeyi 21 ("Lollipop"; Android 5.0) veya üstü) daha yeni bir sürüm seçmeniz gerekir. 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 Desteklenenlere ilişkin dağıtım bilgilerini görüntülemek için Seçmeme yardım et bağlantısı Android SDK'ları Örneğin, Android API düzeyi 21 ("Lollipop"; Android 5.0)'i seçerseniz uygulamanız Android cihazların %99'undan fazlasında çalışır.

   • Derleme yapılandırması dili ayarını Kotlin DSL veya Groovy DSL olarak belirleyin. Aşağıdaki prosedürlerde her iki derleme yapılandırması dili için de snippet'ler gösterilmektedir.

4. Son'u tıklayın.

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

5. Google Maps Görünüm Etkinliği'ni ekleyin:

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

   2. Yeni > Google > Google Haritalar Görünümleri Etkinliği.

      

   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 tamamlandığında Android Studio, AndroidManifest.xml öğesini açar ve MapsActivity dosya. Etkinliğinizin adı farklı olabilir ancak kurulum sırasında yapılandırdığınız addır.

   Dikkat: AndroidManifest.xml dosyası, bir Google Maps API anahtarı ve ardından local.properties dosyanıza eklemek. API anahtarınızı local.properties dosyasına eklemeyin. Bu durumda API anahtarınız daha az güvenli bir şekilde depolanır. Bunun yerine, Cloud projesi oluşturmak ve API anahtarı yapılandırmak için Google Cloud projenizi ayarlama başlıklı makaledeki talimatları uygulayın.

Google Cloud projenizi oluşturun

Şu simgeyi tıklayarak gerekli Cloud Console kurulum adımlarını tamamlayın: ekleyebilirsiniz:

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 etkinleştirildiğinden emin olun.

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

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

ziyaret edin.

Not: Oluşturduğunuz kaynakları tutmayı düşünmüyorsanız öğrenme alıştırmasında, mevcut bir projeyi seçmek yerine bir proje oluşturmalıdır. Bitirdiğinizde Bu alıştırmada projeyi silerek projeyle ilişkili tüm kaynakları kaldırabilirsiniz.

2. Adım

Google Haritalar Platformu'nu kullanmak için projenizle 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 işlemi gerçekleştirilir. API anahtarınızı üretimde kullanıyorsanız API anahtarınızı kısıtlamanızı önemle tavsiye ederiz. Daha fazla bilgi için ürüne özel API Anahtarları Kullanma sayfasına gidin.

API anahtarı, şunun için projenizle ilişkili isteklerin kimliğini doğrulayan benzersiz bir tanımlayıcıdır: yalnızca kullanım ve faturalandırma için değil. Projenizle ilişkilendirilmiş en az bir API anahtarınız olmalıdır.

API anahtarı oluşturmak için:

Konsol

1. Google Haritalar Platformu'na gidin > Credentials (Kimlik Bilgileri) sayfasını ziyaret edin.

   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şturulan API anahtarınız gösterilir.
3. Kapat'ı tıklayın.
   Yeni API anahtarı, Kimlik bilgileri sayfasında API anahtarları altında listelenir.
   (API'yi kısıtlamayı unutmayın. anahtarının doğru şekilde yüklenmesini sağlayın.)

Google Cloud SDK

gcloud alpha 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 alpha services api-keys create

API anahtarını uygulamanıza ekleme

Bu bölümde, web siteleri tarafından güvenli bir şekilde referans verilebilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. en iyi şekilde yararlanabilirsiniz. API anahtarınızı sürüm kontrol sisteminize kontrol etmemeniz gerekir, bu nedenle dosyayı, uygulamanızın kök dizininde bulunan secrets.properties dosyasında depolayarak belirler. 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.

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

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

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

   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çıp 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. Dosyayı kaydedin ve projenizi Gradle ile senkronize edin.
5. secrets.properties dosyasını en üst düzey dizininizde açın ve şunu ekleyin: aşağıdaki kodu kullanabilirsiniz. YOUR_API_KEY yerine API anahtarınızı girin. secrets.properties, sürüm kontrol sistemine kontrol edilmekten hariç tutulduğu 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. Dosyayı kaydedin.

7. Üst düzey dizininizde local.defaults.properties dosyasını oluşturun. klasörünü secrets.properties dosyası olarak kaydedin, ardından aşağıdaki kodu ekleyin.

   Not: Kodu gösterildiği gibi girin. DEFAULT_API_KEY yerine API anahtarınızı koymayın.

   MAPS_API_KEY=DEFAULT_API_KEY

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

8. Dosyayı kaydedin.
9. AndroidManifest.xml dosyanızda şuna gidin: com.google.android.geo.API_KEY ve android:value attribute öğesini 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 için Haritalar SDK'sı da dahil olmak üzere Android platformundaki birden fazla Google Haritalar tabanlı API'de kimlik doğrulaması yapmak için kullanılabilir. Geriye dönük uyumluluk için API ayrıca com.google.android.maps.v2.API_KEY adını destekler. Bu eski ad yalnızca Android Maps API v2'de kimlik doğrulamasına olanak tanır. Bir uygulama, API anahtarı meta veri adlarından yalnızca birini belirtebilir. Her ikisi de belirtilirse API bir istisna oluşturur.

10. Android Studio'da modül düzeyindeki build.gradle.kts veya build.gradle dosyanızı açıp secrets mülkünü düzenleyin. Öğe secrets mülkü mevcut değil, ekleyin.

    propertiesFileName eklentisini şuna ayarlamak için eklentinin özelliklerini düzenleyin: secrets.properties, defaultPropertiesFileName değerini şu şekilde ayarla: 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"
    
        // 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.*"
    }
            

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

Koda bakın

Şablon tarafından sağlanan kodu inceleyin. Özellikle aşağıdaki konulara bakın: dosyaları oluşturun.

Haritalar etkinlik dosyası

Haritalar etkinlik dosyası, uygulamanın ana etkinliğidir ve haritayı yönetmek ve görüntülemek için gereken kodu içerir. Varsayılan olarak, MapsActivity.java adlı etkinliği tanımlarsa veya uygulamanızın dili (MapsActivity.kt)

Haritalar etkinliğinin ana öğeleri:

• SupportMapFragment nesnesi, yaşam döngüsünü oluşturur ve uygulamanın kullanıcı arayüzünün üst öğesidir.

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

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

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

Modül Gradle dosyası

build.gradle.kts adlı Modül dosyası şu harita bağımlılığını içerir: Android için Haritalar SDK'sı tarafından gereklidir.

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 bölümüne bakın.

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 dizinindedir. activity_maps.xml dosyası aşağıdaki öğeleri içeren bir parça tanımlar:

• tools:context, parçanın varsayılan etkinliğini ayarlar Haritalar etkinlik dosyasında tanımlanan MapsActivity adresine.
• android:name, haritalar etkinlik dosyasında kullanılan parça türü olan SupportMapFragment olarak parçanın sınıf adını 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ılı bir şekilde çalıştırdığınızda, ortalanmış olan harita Aşağıdaki ekran görüntüsünde görüldüğü gibi, şehrin üzerinde bir işaretçi bulunan Sidney Avustralya.

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

1. Android Studio'da Çalıştır menü seçeneğini (veya oynat düğmesi simgesini) tıklayarak yardımcı olabilir.
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 emülator (Emülatörü başlat) radyo düğmesini ve sanal cihazdır.
3. Tamam'ı tıklayın. Android Studio, uygulamanızı derlemek için Gradle'i başlatır ve ardından sonuçları cihazınızda veya emülatörde gösterir. Uygulamanın yüklenmesi birkaç dakika sürebilir lansman sonrasında gerçekleşebilir.

Sonraki adımlar

• Harita oluşturma: Bu doküman haritanız için başlangıç ve çalışma zamanı ayarlarını nasıl yapacağınızı açıklar. Kamera konumu, harita türü, kullanıcı arayüzü bileşenleri ve hareketler gibi.

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

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