Android Studio projesi oluşturma

Bu sayfada, Hızlı Başlangıç'ta ayrıntılı olarak açıklanan Google Haritalar şablonu kullanılmadan bir Android Studio projesinin Android için Haritalar SDK'sını kullanacak şekilde nasıl yapılandırılacağı açıklanmaktadır.

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

1. Adım: Android Studio'yu kurun

Bu dokümanda, Android Studio Hedgehog ve Android Gradle eklentisi 8.2 sürümünün kullanıldığı bir geliştirme ortamı açıklanmaktadır.

Not: Geliştirme ortamınız Android Studio veya Gradle'ın farklı bir sürümünü kullanı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 edinmek için Android Gradle eklentisi ve Android Studio uyumluluğu bölümüne bakın.

2. adım: SDK'yı ayarlama

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

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

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

2. Üst düzey settings.gradle dosyanıza, dependencyResolutionManagement bloğunun altına Google'ın Maven deposunu ve Maven merkezi deposunu ekleyin:

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

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

   Modern

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

   Kotlin

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

4. Modül düzeyindeki build.gradle dosyanızda compileSdk ve minSdk değerlerini aşağıdaki değerlere ayarlayın:
   Not: compileSdk değerinin 34 veya daha yüksek bir değere ve minSdk değerinin 21 veya daha yüksek bir değere ayarlandığından emin olun.

   Modern

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

   Kotlin

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

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

   Modern

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

   Kotlin

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

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

Bu bölümde, uygulamanız tarafından güvenli bir şekilde referans verilebilmesi için API anahtarınızı nasıl depolayacağınız açıklanmaktadır. API anahtarınızı sürüm kontrol sisteminizde kontrol etmemeniz gerekir. 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 ö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.

Not: En son sistem gereksinimleri ve yükleme talimatları için GitHub'daki Secrets Gradle Plugin for Android dokümanlarına 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 plugins öğesine aşağıdaki kodu 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. En üst düzey dizininizde secrets.properties dosyasını açın ve ardından aşağıdaki kodu ekleyin. YOUR_API_KEY kısmını API anahtarınızla değiştirin. secrets.properties, sürüm kontrol sistemine kontrol edilmekten hariç tutulduğu için anahtarınızı bu dosyada depolayın.
   Not: secrets.properties dosyası mevcut değilse bu 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ı en üst düzey dizininizde, secrets.properties dosyasıyla aynı klasörde oluşturun ve aşağıdaki kodu ekleyin.

   Not: Kodu gösterildiği gibi girin. DEFAULT_API_KEY öğesini kendi 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 konum sağlayarak derlemelerin başarısız olmasını 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 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 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.*"
    }
            

4. Adım: Uygulama manifestini güncelleyin

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

Google Play hizmetleri sürüm numarası

application öğesine aşağıdaki beyanı ekleyin. Bu işlem, 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 iznini istemeniz gerekir. Seçenekler, tam cihaz konumunu sağlayan ACCESS_FINE_LOCATION ve daha az kesin olan ACCESS_COARSE_LOCATION şeklindedir. Ayrıntılar için konum verileri kılavuzuna göz atın.

Not: quickstart ACCESS_FINE_LOCATION etkinleştirildi.

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

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

Harici depolama izni

Google Play Hizmetleri SDK'sının 8.3 veya sonraki bir sürümünü 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" />

Eski Apache HTTP kitaplığı

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

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

5. Adım: Android cihaz kurun

Android için Haritalar SDK'sını kullanan bir uygulamayı çalıştırmak istiyorsanız bu uygulamayı, Android 5.0 veya sonraki sürümleri tabanlı 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ü kullanmak için sanal bir 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ı seçerseniz Play Store sütununun altında Play simgesi () bulunan bir cihaz seçtiğinizden emin olun. Bu simge, bu profillerin tamamen CTS uyumlu olduğunu ve Play Store uygulamasını içeren sistem resimlerini kullanabileceğini gösterir:

  

6. Adım: İsteğe bağlı olarak Play Hizmeti desteği olup olmadığını kontrol edin

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

Sonraki adımlar

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