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. Ayarlamak istediğiniz mevcut bir Android Studio projeniz varsa Android Studio projesi oluşturma bölümüne bakın.

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.

Android cihaz kurulumu

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 Donanım cihazında uygulama çalıştırma sayfasındaki 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.

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'yi tıklayın.

2. Yeni Proje penceresinde, Telefon ve Tablet kategorisinde 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 desteklenmektedir. 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ü (Android API Düzeyi 21 ("Lollipop"; Android 5.0) veya sonraki bir sürüm" için gereken minimum sürümden daha büyük 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.

   • Derleme yapılandırması dili ayarını Kotlin DSL veya Groovy DSL olarak belirleyin. 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'i başlatır ve projeyi derler. Bu işlem zaman alabilir.

5. Google Haritalar Görüntüleme Etkinliği'ni ekleyin:

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

   2. Yeni > Google > Google Maps Görünüm 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 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 addır.

Google Cloud projenizi ayarlama

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

gcloud projects create "PROJECT"

gcloud services enable \
    --project "PROJECT" \
    "maps-android-backend.googleapis.com"

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

API anahtarını uygulamanıza ekleme

Bu bölümde, API anahtarınızı uygulamanız tarafından güvenli bir şekilde referans verilebilmesi için nasıl saklamanız gerektiği açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminize eklememeniz gerektiğinden, anahtarı projenizin kök dizininde bulunan secrets.properties dosyasında saklamanızı öneririz. secrets.properties dosyası hakkında daha fazla bilgi için Gradle özellikleri dosyaları bölümüne bakın.

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

Android için Secrets Gradle eklentisini Google Haritalar projenize 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çı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. Üst düzey dizininizdeki secrets.properties dosyasını açıp aşağıdaki kodu ekleyin. YOUR_API_KEY kısmını API anahtarınızla değiştirin. secrets.properties, bir sürüm kontrol sistemine kontrol edilmekten hariç tutulduğu için anahtarınızı bu dosyada saklayın.

   MAPS_API_KEY=YOUR_API_KEY

6. Dosyayı kaydedin.

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

   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. 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 ortaya çıkabilir.

8. Dosyayı kaydedin.
9. AndroidManifest.xml dosyanızda com.google.android.geo.API_KEY bölümüne gidip android:value attribute dosyasını güncelleyin. <meta-data> etiketi yoksa bu etiketi <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.kts or build.gradle 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.

    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 Android Studio projenizde aşağıdaki dosyalara bakın.

Haritalar etkinliği dosyası

Haritalar etkinlik dosyası, uygulamanın ana etkinliğidir ve haritayı yönetmek ve görüntülemek için gereken kodu içerir. Etkinliği tanımlayan dosya varsayılan olarak MapsActivity.java olarak adlandırılır. Uygulamanızın dilini Kotlin olarak ayarlarsanız 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. SupportMapFragment ve GoogleMap nesneleri, Harita Nesneleri kılavuzunda daha ayrıntılı olarak açıklanmaktadır.

• moveCamera işlevi, haritayı Sidney'in LatLng koordinatlarında ortalar. Harita eklerken yapılandırmanız gereken ilk ayarlar genellikle harita konumu ve kamera ayarlarından (ör. görüntüleme açısı, harita yönü ve yakınlaştırma düzeyi) oluşur. Ayrıntılar için Kamera ve Görünüm 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 modülü dosyası, Android için Haritalar SDK'sı tarafından gereken aşağıdaki Haritalar bağımlılığını içerir.

dependencies {

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

Haritalar bağımlılığını yönetme hakkında daha fazla bilgi edinmek için Sürümlendirme 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, haritalar etkinlik dosyasında tanımlanan MapsActivity değerini, parçanın varsayılan etkinliği olarak ayarlar.
• android:name, parçanın sınıf adını, harita etkinlik 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ılı bir şekilde çalıştırdığınızda, aşağıdaki ekran görüntüsünde görüldüğü gibi, Sidney Avustralya'yı merkez alan bir harita ve şehir üzerinde bir işaretçi gösterilir.

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

1. Uygulamanızı çalıştırmak için Android Studio'da Ç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, Emülatörü başlat radyo düğmesini ve ardından ayarladığınız sanal cihazı seçin.
3. Tamam'ı tıklayın. Android Studio, uygulamanızı derlemek için Gradle'ı başlatır, 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 için kamera konumu, harita türü, kullanıcı arayüzü bileşenleri ve hareketler gibi ilk ve çalışma zamanı ayarlarının 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 uygulamada yol gösterici bilgiler sağlanmaktadır.

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