Android Studio projesi oluşturma

Bu sayfada, Hızlı Başlangıç'da ayrıntılı olarak açıklanan Google Haritalar şablonunu kullanmadan Android için Haritalar SDK'sını kullanmak üzere bir Android Studio projesinin nasıl yapılandırılacağı açıklanmaktadır.

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

1. Adım: Android Studio'yu kurun

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

2. adım: SDK'yı ayarlama

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

  1. Üst düzey settings.gradle dosyanızda, pluginManagement bloğunun altında Gradle eklenti portalı, Google Maven deposu ve Maven merkezi deposu'nu 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 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ının Google Play Hizmetleri bağımlılığını ekleyin.

    Modern

    dependencies {
    
        // Maps SDK for Android
        implementation 'com.google.android.gms:play-services-maps:18.2.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:

    Modern

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

    Kotlin

    android {
        compileSdk = 34
    
        defaultConfig {
            minSdk = 19
            // ...
        }
    }
  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ı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.

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

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

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ı

Aşağıdaki beyanı application öğesine ekleyin. Bu işlev, 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ızdan konum izni istemeniz gerekir. Seçenekler, cihaz konumunu tam olarak sağlayan ACCESS_FINE_LOCATION ve daha az kesin olan ACCESS_COARSE_LOCATION şeklindedir. Ayrıntılı bilgi için konum verileri kılavuzuna bakın.

ACCESS_FINE_LOCATION iznini istemek için şu 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 bir sürümünü hedefliyorsanız WRITE_EXTERNAL_STORAGE iznine ihtiyacınız yoktur. Google Play Hizmetleri SDK'sının daha eski 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 daha eski bir sürümü kullanıyorsanız ve uygulamanız API düzeyi 28 (Android 9.0) veya üstünü hedefliyorsa AndroidManifest.xml öğesinin <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 kurun

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.

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

Android için Haritalar SDK'sı, uygulamanızı dağıttığınız cihazda Google Play hizmetlerinin 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 hizmetlerinin yüklü olup olmadığını kontrol etme bölümüne bakın.

Sonraki adımlar

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