Android Studio projesi oluşturma

Bu sayfada, Android için Haritalar SDK'sını kullanmak üzere bir Android Studio projesinin nasıl yapılandırılacağı açıklanmaktadır. Bu yapılandırma, Hızlı Başlangıç bölümünde ayrıntılı olarak açıklanan Google Haritalar şablonu kullanılmadan yapılır.

Google Haritalar şablonu, yeni bir Android Studio projesini otomatik olarak yapılandırır ve temel bir harita ekler. Ancak farklı bir Android Studio şablonu kullanan bir Android projesine de harita ekleyebilirsiniz. Bunun için projenizi manuel olarak yapılandırmanız ve ardından haritayı eklemeniz gerekir.

1. adım: Android Studio'yu kurun

Bu belgede, Android Studio Hedgehog ve Android Gradle eklentisi 8.2 sürümünü kullanan bir geliştirme ortamı açıklanmaktadır.

Not: Geliştirme ortamınızda Android Studio veya Gradle'ın farklı bir sürümü kullanılıyorsa adımları bu sürümlere 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.

2. adım: SDK'yı ayarlama

Android için Haritalar SDK'sı kitaplığına Google'ın Maven deposundan erişebilirsiniz. SDK'yı uygulamanıza eklemek için aşağıdakileri yapın:

1. En üst düzeydeki settings.gradle.kts dosyanızda, pluginManagement bloğunun altına Gradle eklenti portalını, Google Maven deposunu ve Maven merkezi deposunu ekleyin. pluginManagement bloğu, komut dosyasındaki diğer ifadelerden önce görünmelidir.

   pluginManagement {
       repositories {
           google()
           mavenCentral()
           gradlePluginPortal()
       }
   } 

2. En üst düzeydeki settings.gradle.kts dosyanızda, dependencyResolutionManagement bloğunun altına Google'ın Maven deposunu ve Maven merkezi deposunu ekleyin:

   dependencyResolutionManagement {
       repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
       repositories {
           google()
           mavenCentral()
       }
   } 

3. Modül düzeyindeki build.gradle.kts veya build.gradle dosyanıza Android için Haritalar SDK'sının Google Play Hizmetleri bağımlılığını ekleyin.

   Kotlin

   dependencies {
   
       // Maps SDK for Android
       implementation(libs.play.services.maps)
   }

   Modern

   dependencies {
   
       // Maps SDK for Android
       implementation "com.google.android.gms:play-services-maps:20.1.0"
   }

4. Modül düzeyindeki build.gradle.kts veya build.gradle dosyanızda compileSdk ve minSdk değerlerini aşağıdaki gibi ayarlayın:
   Not: compileSdk değerinin 34 veya daha yüksek, minSdk değerinin ise 23 veya daha yüksek olarak ayarlandığından emin olun.

   Kotlin

   android {
       compileSdk = 34
   
       defaultConfig {
           minSdk = 23
           // ...
       }
   }

   Modern

   android {
       compileSdk 34
   
       defaultConfig {
           minSdk 23
           // ...
       }
   }

5. Modül düzeyindeki build.gradle.kts veya build.gradle dosyanızın buildFeatures bölümüne, bu prosedürde daha sonra tanımlanan meta veri değerlerine erişmek için kullanabileceğiniz BuildConfig sınıfını ekleyin:

   Kotlin

   android {
     // ...
     buildFeatures {
       buildConfig = true
       // ...
     }
   }

   Modern

   android {
     // ...
     buildFeatures {
       buildConfig true
       // ...
     }
   }

6. libs.versions.toml dosyanıza aşağıdakileri ekleyin:

   [versions]
   play-services-maps = "20.1.0"
   
   [libraries]
   play-services-maps = { module = "com.google.android.gms:play-services-maps", version.ref = "play-services-maps" }
       

3. adım: API anahtarınızı projeye ekleyin

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 dizinindeki bir secrets.properties dosyasına kaydetmenizi ve bu dosyayı sürüm denetiminden hariç tutmanızı öneririz. Gradle özellik dosyaları hakkında daha fazla bilgi için Gradle özellik dosyaları konusuna bakın.

Bu görevi basitleştirmek 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 en üst düzey build.gradle.kts veya build.gradle dosyanızı açın ve aşağıdaki kodu plugins bloğuna ekleyin.

   Kotlin

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

   Modern

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

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

   Kotlin

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

   Modern

   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. 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. API anahtarınızı sürüm denetimine eklememek için secrets.properties dosyanıza .gitignore eklediğinizden (veya sürüm denetim sisteminizden hariç tuttuğunuzdan) emin olun.
   Not: secrets.properties dosyası yoksa local.properties dosyasıyla aynı klasörde oluşturun.

   MAPS_API_KEY=YOUR_API_KEY

5. En ü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, uygulamayı secrets.properties dosyasını atlayan bir sürüm denetim sisteminden klonladıysanız ve API anahtarınızı sağlamak için yerel olarak bir secrets.properties dosyası oluşturmadıysanız ortaya çıkabilir.

6. 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: API anahtarı için önerilen meta veri adı com.google.android.geo.API_KEY'dir. 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ğrulamasına izin verir. Bir uygulama yalnızca API anahtarı meta veri adlarından birini belirtebilir. Her ikisi de belirtilirse API istisna oluşturur.

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

   Kotlin

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

4. adım: Uygulama manifestini güncelleyin

Bu bölümde, AndroidManifest.xml dosyanıza eklemeniz gereken ayarlar açıklanmaktadır.

Google Play Hizmetleri sürüm numarası

application öğesine aşağıdaki beyanı ekleyin. Bu, uygulamanın derlendiği Google Play Hizmetleri sürümünü yerleştirir.

<meta-data
    android:name="com.google.android.gms.version"
    android:value="@integer/google_play_services_version"/>

Konum izni

Uygulamanızın kullanıcının konumuna erişmesi gerekiyorsa AndroidManifest.xml dosyanızda konum izni istemeniz gerekir. Seçenekler, cihazın tam konumunu sağlayan ACCESS_FINE_LOCATION ve daha az hassas olan ACCESS_COARSE_LOCATION'dir. Ayrıntılar için konum verileri kılavuzuna bakın.

Not: Hızlı başlangıç'ta ACCESS_FINE_LOCATION etkinleştirilmiştir.

ACCESS_FINE_LOCATION iznini istemek için bu kodu manifest öğesine ekleyin:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

Harici depolama izni

Google Play Hizmetleri SDK'sının 8.3 veya sonraki sürümlerini hedefliyorsanız WRITE_EXTERNAL_STORAGE iznine ihtiyacınız yoktur. Google Play Hizmetleri SDK'sının önceki sürümlerini hedefliyorsanız manifest öğesinde WRITE_EXTERNAL_STORAGE iznini istemeniz gerekir.

<uses-permission
        android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

Apache HTTP Legacy kitaplığı

com.google.android.gms:play-services-maps:16.0.0 veya daha eski bir sürüm kullanıyorsanız ve uygulamanız hedef API düzeyi 28 (Android 9.0) veya sonraki sürümleri hedefliyorsa AndroidManifest.xml dosyasının <application> öğesine aşağıdaki beyanı eklemeniz gerekir. Aksi takdirde bu beyanı atlayın.

<uses-library
    android:name="org.apache.http.legacy"
    android:required="false"/>

5. adım: Android cihaz kurma

Android için Haritalar SDK'sını kullanan bir uygulamayı çalıştırmak istiyorsanız uygulamayı Android 6.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 cihazda ç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 Cihaz Yönetim Paneli'ni kullanarak emülatörü yükleyebilirsiniz.
  Not: Android emülatörü kullanmayı tercih ederseniz Play Store sütununda Play simgesi () bulunan bir cihaz profili seçtiğinizden emin olun. Bu simge, bu profillerin CTS ile tam uyumlu olduğunu ve Google Play Store uygulamasını içeren sistem görüntülerini kullanabileceğini gösterir.

6. adım: İsteğe bağlı olarak Play Hizmetleri desteğini kontrol edin

Android için Haritalar SDK'sı, uygulamanızı dağıttığınız cihazda Google Play Hizmetleri'nin yüklü olmasını gerektirir. Google, kontrol etmek için uygulamanızdan çağırabileceğiniz bir yöntem sunar. Daha fazla bilgi için Google Play Hizmetleri'nin yüklü olup olmadığını kontrol etme başlıklı makaleyi inceleyin.

Sonraki adımlar

Projeniz yapılandırıldıktan sonra harita ekleyebilirsiniz.