Android Studio projesi oluşturma

Bu sayfada, Hızlı Başlangıç bölümünde ayrıntılı olarak açıklanan Google Haritalar şablonunu kullanmadan 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, yeni bir Android Studio projesine otomatik olarak temel bir harita yapılandırır ve ekler. Ancak farklı bir Android Studio şablonu kullanan bir Android projesine de harita 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 belgede, Android Studio Hedgehog ve Android Gradle eklentisinin 8.2 sürümünü kullanan bir geliştirme ortamı açıklanmaktadır.

Not: Geliştirme ortamınızda farklı bir Android Studio veya Gradle 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ığı, Google'ın Maven deposundan edinilebilir. SDK'yı uygulamanıza eklemek için aşağıdakileri yapın:

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

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

2. Üst düzey settings.gradle.kts dosyanızda, 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.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("com.google.android.gms:play-services-maps:19.0.0")
   }

   Modern

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

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

   Kotlin

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

   Modern

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

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

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

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 özellik dosyaları konusuna 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 İçin Secrets Gradle Plugin belgelerine bakın.

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 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. local.defaults.properties dosyasını üst düzey dizininizde, secrets.properties dosyasıyla aynı klasörde oluşturun ve 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 com.google.android.geo.API_KEY bölümüne gidin ve android:value attribute değerini 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. 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 ile 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. secrets mülkü yoksa ekleyin.

    propertiesFileName değerini secrets.properties, defaultPropertiesFileName değerini local.defaults.properties ve diğer özellikleri ayarlamak için eklentinin özelliklerini düzenleyin.

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

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, 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 arasında, cihazın tam konumunu sağlayan ACCESS_FINE_LOCATION ve daha az hassas olan ACCESS_COARSE_LOCATION yer alır. Ayrıntılar için konum verileri kılavuzunu inceleyin.

Not: Hızlı başlangıç bölümünde ACCESS_FINE_LOCATION etkindir.

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" />

Apache HTTP eski kitaplığı

com.google.android.gms:play-services-maps:16.0.0 veya önceki bir sürümü kullanıyorsanız ve uygulamanız API düzeyi 28'i (Android 9.0) veya üstünü 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ı 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ı tercih ederseniz 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 Hizmetleri'nin yüklü olmasını gerektirir. Google, kontrol etmek için uygulamanızdan çağırabileceğiniz bir yöntem sağlar. 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.