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 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, yeni bir Android Studio projesinde temel bir haritayı otomatik olarak yapılandırır ve 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ün kullanıldığı bir geliştirme ortamı açıklanmaktadır.

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 {
        gradlePluginPortal()
        google()
        mavenCentral()
    }
}
  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.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ı için 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 değerlerini aşağıdaki gibi ayarlayın:

    Kotlin

    android {
    compileSdk = 34

    defaultConfig {
        minSdk = 21
        // ...
    }
}

    Modern

    android {
    compileSdk 34

    defaultConfig {
        minSdk 21
        // ...
    }
}
  5. Modül düzeyindeki buildFeatures 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:build.gradle.kts

    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ı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 kontrol sisteminize işlememeniz gerekir. Bu nedenle, anahtarınızı projenizin kök dizininde bulunan secrets.properties dosyasına kaydetmenizi ö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 İçin Secrets Gradle Plugin'i kullanmanızı öneririz.

Google Haritalar projenize Android İçin Secrets Gradle Plugin'i 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çın ve 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. Projenizi Gradle ile senkronize edin.
  5. 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. secrets.properties, sürüm kontrol sistemine dahil edilmediği için anahtarınızı bu dosyada saklayın. 
    MAPS_API_KEY=YOUR_API_KEY

  6. Üst düzey dizininizde, secrets.properties dosyasıyla aynı klasörde local.defaults.properties dosyasını 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ğlamaktır. Böylece derlemeler başarısız olmaz. Bu durum, secrets.properties öğesini atlayan bir sürüm kontrol sisteminden uygulamayı klonlarsanız ve API anahtarınızı sağlamak için henüz yerel olarak bir secrets.properties dosyası oluşturmadıysanız meydana gelebilir.

  7. 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 platformundaki Android için Haritalar SDK'sı da dahil olmak üzere 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'de kimlik doğrulamasına izin verir. Bir uygulama yalnızca API anahtarı meta veri adlarından birini belirtebilir. Her ikisi de belirtilirse API bir istisna oluşturur.

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

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

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

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 izni istemeniz gerekir. Seçenekler arasında tam cihaz 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ılavuzuna bakın.

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 önceki sürümleri kullanıyorsanız ve uygulamanız API düzeyi 28'i (Android 9.0) ya da sonraki sürümleri hedefliyorsa AndroidManifest.xml öğesinin <application> öğesine aşağıdaki bildirimi 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 için uygulamayı Android 5.0 veya sonraki sürümlere dayalı 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 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 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, uygulamanızdan çağırarak kontrol edebileceğ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.