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

Android Studio için Google Haritalar Görünümler şablonunu kullanarak harita görüntüleyen bir Android uygulaması oluşturun. Oluşturmak istediğiniz mevcut bir Android Studio projeniz varsa bkz. Android Studio projesi oluşturma.

Bu hızlı başlangıç kılavuzu, Kotlin veya Java ile temel Android geliştirme konusunda bilgi sahibi olan geliştiricilere yöneliktir.

Geliştirme ortamı hakkında

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

Not: Geliştirme ortamınız farklı bir Android Studio veya Gradle sürümü kullanıyorsa adımları ortamınıza bağlı olarak 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 bölümünü inceleyin.

Android cihaz kurma

Android için Haritalar SDK'sını kullanan bir uygulamayı çalıştırmak istiyorsanız bu uygulamayı, Android 4.0 veya sonraki bir sürümünü 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ü kullanmak için sanal bir cihaz oluşturabilir ve Android Studio ile birlikte gelen Android Virtual Device (AVD) Manager'ı kullanarak emülatörü yükleyebilirsiniz.
  Not: Android emülatörü kullanmayı tercih ederseniz Play Store sütunu altında Play simgesi () bulunan bir cihaz seçtiğinizden emin olun. Bu simge, söz konusu profillerin tamamen CTS ile 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ü Flamingo'da ve Android Studio'nun sonraki sürümlerinde değiştirildi.

1. Android Studio'yu açın ve Android Studio'ya hoş geldiniz penceresinde Yeni Proje Oluştur'u tıklayın.

2. Yeni Proje penceresindeki Telefon ve Tablet kategorisi altında Etkinlik Yok'u seçip İ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 bölümüne bakın.

   • Minimum SDK'yı, test cihazınızla uyumlu bir SDK sürümüne ayarlayın. Android için Haritalar SDK'sı Android API Seviye 19 ("KitKat"; Android 4.4) veya sonraki bir sürüm için Haritalar SDK'sı sürüm 18.2.x için gereken minimum sürümden daha yüksek bir sürüm seçmelisiniz. SDK sürümü gereksinimleriyle ilgili en güncel 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ıyla ilgili dağıtım bilgilerini görüntülemek için Seçmeme yardım et bağlantısını seçin. Örneğin, Android API Düzey 19 ("KitKat"; Android 4.4) seçeneğini belirlerseniz 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österilir.

4. Son'u tıklayın.

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

5. Google Maps Views Etkinliği'ni ekleyin:

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

   2. Yeni > Google > Google Haritalar Görünüm Etkinliği'ni seçin.

      

   3. Yeni Android Etkinliği iletişim kutusunda Başlatıcı Etkinliği onay kutusunu seçin.

   4. Son'u seçin.

      Daha fazla bilgi için Şablondan kod ekleme bölümüne bakın

6. Derleme tamamlandığında Android Studio AndroidManifest.xml ve MapsActivity dosyalarını açar. Etkinliğinizin farklı bir adı olabilir, ancak kurulum sırasında yapılandırdığınız etkinliktir.

   Dikkat: AndroidManifest.xml dosyası, bir Google Haritalar API anahtarı edinme ve ardından bu anahtarı local.properties dosyanıza ekleme hakkında talimatlar içerir. API anahtarınızı local.properties dosyasına eklemeyin. Bu işlem, API anahtarınızı daha az güvenli bir şekilde depolar. Bunun yerine, Cloud projesi oluşturmak ve API anahtarı yapılandırmak için Google Cloud projenizi oluşturma bölümündeki talimatları uygulayın.

Google Cloud projenizi oluşturun

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

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ğini onaylayın.

   Google Cloud, 0,00 ABD doları tutarında ücretsiz deneme süresi sunar. Deneme, hangisinin önce gerçekleştiğine bağlı olarak, 90 günün sonunda veya hesaba 300 ABD doları tutarında maliyet tahakkuk ettikten sonra sona erer. Dilediğiniz zaman iptal edebilirsiniz. Google Haritalar Platformu'nda aylık 200 ABD doları değerinde yinelenen bir kredi bulunur. Daha fazla bilgi için Faturalandırma hesabı kredileri ve Faturalandırma bölümlerine bakın.

Google Cloud SDK

gcloud projects create "PROJECT"

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

• gcloud projects create

Not: Oluşturduğunuz kaynakları bir öğrenim alıştırmasında tutmayı düşünmüyorsanız mevcut bir projeyi seçmek yerine 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, Google 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ım yalnızca API Anahtarı oluşturma sürecinden geçer. 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 amaçları doğrultusunda 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örüntülenir.
3. Kapat'ı tıklayın.
   Yeni API anahtarı, API anahtarları altındaki Kimlik Bilgileri sayfasında listelenir.
   (Üretimde kullanmadan önce API anahtarını kısıtlamayı unutmayın.)

Google Cloud SDK

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

Google Cloud SDK, Google 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, uygulamanızın güvenli bir şekilde başvuruda bulunabilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize kontrol etmemelisiniz. Bu nedenle, projenizin kök dizininde bulunan secrets.properties dosyasında saklamanızı öneririz. secrets.properties dosyası hakkında daha fazla bilgi için Gradle özelliği dosyaları bölümüne bakın.

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

Not: En güncel sistem gereksinimleri ve yükleme talimatları için GitHub'daki Android iç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 veya build.gradle.kts dosyanızı açın ve aşağıdaki kodu buildscript altındaki dependencies öğesine 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. Modül düzeyindeki build.gradle dosyanızı açın ve aşağıdaki kodu plugins öğesine ekleyin.

   Modern

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

   Kotlin

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

3. Modül düzeyindeki build.gradle dosyanızda targetSdk ve compileSdk öğelerinin 34 olarak ayarlandığından emin olun.
4. Dosyayı kaydedin ve projenizi Gradle ile senkronize edin.
5. Üst düzey dizininizde secrets.properties dosyasını açın, ardından aşağıdaki kodu ekleyin. YOUR_API_KEY öğesini API anahtarınızla değiştirin. secrets.properties, sürüm kontrol sistemine kontrol edilemiyor. Bu nedenle anahtarınızı bu dosyada saklayın.
   Not: secrets.properties dosyası mevcut değilse dosyayı local.properties dosyasıyla aynı klasörde oluşturun.

   MAPS_API_KEY=YOUR_API_KEY

6. Dosyayı kaydedin.

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

   Not: Kodu gösterildiği gibi 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ı için yedek konum sağlamaktır. Uygulamayı secrets.properties içermeyen bir sürüm kontrol sisteminden klonlarsanız ve henüz API anahtarınızı sağlamak için yerel olarak bir secrets.properties dosyası oluşturmadıysanız bu durum görülebilir.

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

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

   Note: com.google.android.geo.API_KEY is the recommended metadata name for the API key. A key with this name can be used to authenticate to multiple Google Maps-based APIs on the Android platform, including the Maps SDK for Android. For backwards compatibility, the API also supports the name com.google.android.maps.v2.API_KEY. This legacy name allows authentication to the Android Maps API v2 only. An application can specify only one of the API key metadata names. If both are specified, the API throws an exception.

10. In Android Studio, open your module-level build.gradle or build.gradle.kts file and edit the secrets property. If the secrets property does not exist, add it.

    Edit the properties of the plugin to set propertiesFileName to secrets.properties, set defaultPropertiesFileName to local.defaults.properties, and set any other properties.

    Groovy

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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.*"
    }
            

    Kotlin

    secrets {
        // Optionally specify a different file name containing your secrets.
        // The plugin defaults to "local.properties"
        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 Android Studio projenizde aşağıdaki dosyalara bakın.

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, etkinliği tanımlayan dosyanın adı MapsActivity.java olur veya Kotlin'i uygulamanızın dili olarak MapsActivity.kt olarak ayarlarsanız.

Harita 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ı Sidney Avustralya için 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üntüleme 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 Modül dosyası, Android için Haritalar SDK'sının gerektirdiği aşağıdaki harita bağımlılığını içerir.

dependencies {

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

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

• 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 etkinlik dosyasında kullanılan parça türüdür.

XML düzen dosyası şu 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, merkezinde Sidney Avustralya'yı gösteren bir harita görüntülenir. Haritanın ortasında, aşağıdaki ekran görüntüsünde görüldüğü gibi, şehirde bir işaretçi bulunur.

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

1. Android Studio'da, uygulamanızı çalıştırmak için Çalıştır menü seçeneğini (veya oynat düğmesi) 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çin ve kurduğunuz 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örüntüler. 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ı (ör. kamera konumu, harita türü, kullanıcı arayüzü bileşenleri ve hareketler) nasıl oluşturacağınız 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 uygulamada sizi yönlendirir.

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