Android Studio projenizi ayarlama

Bu sayfada, Navigation SDK'yı geliştirme projenize nasıl entegre edeceğiniz açıklanmaktadır.

Navigation SDK'yı projenize ekleme

Navigation SDK'ya Google Maven deposu üzerinden erişebilirsiniz. SDK'yı Gradle build.gradle veya Maven pom.xml yapılandırmanızı kullanarak projenize ekleyebilirsiniz.

  1. Android için Navigasyon SDK'sının istediğiniz sürümünü VERSION_NUMBER yer tutucusunun yerine koyarak Gradle veya Maven yapılandırmanıza aşağıdaki bağımlılığı ekleyin.

    Gradle

    Modül düzeyindeki build.gradle dosyanıza aşağıdakileri ekleyin:

    dependencies {
        ...
        implementation 'com.google.android.libraries.navigation:navigation:VERSION_NUMBER'
}

    Maven

    pom.xml dosyanıza aşağıdakileri ekleyin:

    <dependencies>
  ...
  <dependency>
    <groupId>com.google.android.libraries.navigation</groupId>
    <artifactId>navigation</artifactId>
    <version>VERSION_NUMBER</version>
  </dependency>
</dependencies>

  2. Haritalar SDK'sını kullanan bağımlılıklarınız varsa Haritalar SDK'sını kullanan her beyan edilen bağımlılıkta bağımlılığı hariç tutmanız gerekir.

    Gradle

    Üst düzey build.gradle dosyanıza aşağıdakileri ekleyin:

    allprojects {
        ...
        // Required: you must exclude the Google Play service Maps SDK from
        // your transitive dependencies to make sure there won't be
        // multiple copies of Google Maps SDK in your binary, as the Navigation
        // SDK already bundles the Google Maps SDK.
        configurations {
            implementation {
                exclude group: 'com.google.android.gms', module: 'play-services-maps'
            }
        }
}

    Maven

    pom.xml dosyanıza aşağıdakileri ekleyin:

    <dependencies>
  <dependency>
  <groupId>project.that.brings.in.maps</groupId>
  <artifactId>MapsConsumer</artifactId>
  <version>1.0</version>
    <exclusions>
      <!-- Navigation SDK already bundles Maps SDK. You must exclude it to prevent duplication-->
      <exclusion>  <!-- declare the exclusion here -->
        <groupId>com.google.android.gms</groupId>
        <artifactId>play-services-maps</artifactId>
      </exclusion>
    </exclusions>
  </dependency>
</dependencies>

Derlemeyi yapılandırma

Projeyi oluşturduktan sonra, Navigation SDK'nın başarılı bir şekilde derlenmesi ve kullanılması için ayarları yapılandırabilirsiniz.

Yerel mülkleri güncelleme

  • Gradle Scripts klasöründe local.properties dosyasını açın ve android.useDeprecatedNdk=true kodunu ekleyin.

Gradle derleme komut dosyasını güncelleme

  • build.gradle (Module:app) dosyasını açın ve ayarları Navigation SDK'nın gereksinimlerini karşılayacak şekilde güncellemek için aşağıdaki yönergeleri kullanın. Optimizasyon seçeneklerini de ayarlayabilirsiniz.

    Navigation SDK için gerekli ayarlar

    1. minSdkVersion değerini 24 veya daha yüksek bir değere ayarlayın.
    2. targetSdkVersion değerini 36 veya daha yüksek bir değere ayarlayın.
    3. javaMaxHeapSize değerini artıran bir dexOptions ayarı ekleyin.
    4. Ek kitaplıkların konumunu ayarlayın.
    5. Navigasyon SDK'sı için repositories ve dependencies ekleyin.
    6. Bağımlılıklardaki sürüm numaralarını mevcut en son sürümlerle değiştirin.

    Derleme süresini kısaltmak için isteğe bağlı ayarlar

    • Bağımlılıklardan kullanılmayan kodları ve kaynakları kaldırmak için R8/ProGuard kullanarak kod daraltma ve kaynak daraltma özelliğini etkinleştirin. R8/ProGuard adımının çalışması çok uzun sürüyorsa geliştirme çalışmaları için multidex'i etkinleştirebilirsiniz.
    • Derlemeye dahil edilen dil çevirilerinin sayısını azaltın: Geliştirme sırasında bir dil için resConfigs değerini ayarlayın. Son derleme için resConfigs değerini, gerçekten kullandığınız diller olarak ayarlayın. Gradle, varsayılan olarak Navigation SDK tarafından desteklenen tüm diller için kaynak dizeleri içerir.

    Java8 desteği için desugaring ekleme

    • Uygulamanızı Android Gradle eklentisi 4.0.0 veya sonraki bir sürümü kullanarak oluşturuyorsanız eklenti, çeşitli Java 8 dil API'lerinin kullanımına yönelik desteği genişletir. Daha fazla bilgi için Java 8 desugaring desteği başlıklı makaleyi inceleyin. Derleme ve bağımlılık seçeneklerinin nasıl kullanılacağını öğrenmek için aşağıdaki örnek derleme komut dosyası snippet'ine bakın.
    • Navigation SDK sürümünüzle eşleşen Gradle, Android Gradle eklentisi (AGP) ve Desugar kitaplığı sürümlerini kullanın. Aşağıdaki tabloya bakın.
    • Desugar kitaplığının app modülü ve doğrudan Navigasyon SDK'sına bağlı olan tüm modüller için etkinleştirilmesi gerekir.

Aşağıdaki tabloda, her bir Navigation SDK sürümü için gereken Gradle, AGP ve Desugar kitaplığı sürümleri listelenmiştir.

Navigation SDK sürümü Gradle sürümü AGP sürümü Desugar kitaplığı
8.0.0 ve sonraki sürümler 9.1.0 9.0.1 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.7.0 - 7.9.0 8.13 8.13.2 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.3.0 - 7.6.0 8.11.1 8.10.0 com.android.tools:desugar_jdk_libs_nio:2.0.3

Aşağıda, uygulama için Gradle derleme komut dosyası örneği verilmiştir. Kullandığınız Navigation SDK sürümü bu dokümandan biraz daha yeni veya eski olabileceğinden güncellenmiş bağımlılık grupları için örnek uygulamaları inceleyin.

apply plugin: 'com.android.application'

ext {
    navSdk = "__NAVSDK_VERSION__"
}

android {
    compileSdk 33
    buildToolsVersion='28.0.3'

    defaultConfig {
        applicationId "<your id>"
        // Navigation SDK supports SDK 23 and later.
        minSdkVersion 23
        targetSdkVersion 34
        versionCode 1
        versionName "1.0"
        // Set this to the languages you actually use, otherwise you'll include resource strings
        // for all languages supported by the Navigation SDK.
        resConfigs "en"
        multiDexEnabled true
    }

    dexOptions {
        // This increases the amount of memory available to the dexer. This is required to build
        // apps using the Navigation SDK.
        javaMaxHeapSize "4g"
    }
    buildTypes {
        // Run ProGuard. Note that the Navigation SDK includes its own ProGuard configuration.
        // The configuration is included transitively by depending on the Navigation SDK.
        // If the ProGuard step takes too long, consider enabling multidex for development work
        // instead.
        all {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
    compileOptions {
        // Flag to enable support for the new language APIs
        coreLibraryDesugaringEnabled true
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

repositories {
    // Navigation SDK for Android and other libraries are hosted on Google's Maven repository.
    google()
}

dependencies {
    // Include the Google Navigation SDK.
    // Note: remember to exclude Google Play service Maps SDK from your transitive
    // dependencies to avoid duplicate copies of the Google Maps SDK.
    api "com.google.android.libraries.navigation:navigation:${navSdk}"

    // Declare other dependencies for your app here.

    annotationProcessor "androidx.annotation:annotation:1.7.0"
    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs_nio:2.1.5'
}

API anahtarını uygulamanıza ekleme

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 dizininde bulunan secrets.properties dosyasına kaydetmenizi ve bu dosyayı sürüm denetiminin dışında 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 ü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. 
    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.

    MAPS_API_KEY=DEFAULT_API_KEY

    Bu dosyanın amacı, secrets.properties dosyası bulunamazsa derlemelerin başarısız olmaması için API anahtarına yedek bir konum sağlamaktır. 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. API anahtarını AndroidManifest.xml dosyanıza ekleyebilir veya API anahtarını programatik olarak sağlayabilirsiniz.
    • API anahtarınızı AndroidManifest.xml uygulamasına ekleyin: 
      <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 şeklindedir. Bu ada sahip bir anahtar, Android için Navigasyon SDK'sı da dahil olmak üzere Android platformundaki 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ğrulamaya olanak tanır. Bir uygulama, API anahtarı meta veri adlarından yalnızca birini belirtebilir. Her ikisi de belirtilirse API bir istisna oluşturur.

    • API anahtarını programatik olarak sağlayın:

      Secrets Gradle Plugin, anahtarı BuildConfig sınıfında kullanılabilir hale getirir. Uygulamanızın başlatma işleminde (örneğin, Application.onCreate() yönteminizde) yöntemi aşağıdaki gibi çağırın:

      Kotlin

      1. Aşağıdaki içe aktarma ifadelerini ekleyin: 
        import com.google.android.libraries.navigation.NavigationApi
      2. Application.onCreate() yönteminize aşağıdakileri ekleyin: 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. Aşağıdaki içe aktarma ifadelerini ekleyin: 
        import com.google.android.libraries.navigation.NavigationApi;
      2. Application.onCreate() yönteminize aşağıdakileri ekleyin: 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      Not: setApiKey() kullanırken aşağıdakileri göz önünde bulundurun:
      • Boş olmayan bir API anahtarı girin.
      • setApiKey() yöntemini uygulamanızın kullanım süresi boyunca yalnızca bir kez çağırın. Yöntem, birden fazla kez çağrılırsa IllegalStateException hatası verir.
      • Navigator gibi diğer Navigasyon SDK'sı bileşenlerini başlatmadan önce setApiKey() yöntemini çağırın.
      • Bu yöntemle sağladığınız anahtar, AndroidManifest.xml dosyanızdaki tüm API anahtarlarını geçersiz kılar.
      • Navigation SDK'nın 7.6 veya sonraki bir sürümünü kullanın.

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

Uygulamanıza gerekli atıfları ekleme

Uygulamanızda Android için Navigasyon SDK'sını kullanıyorsanız uygulamanızın yasal uyarılar bölümüne atıf metni ve açık kaynak lisansları eklemeniz gerekir.

Gerekli atıf metnini ve açık kaynak lisanslarını Android için Navigasyon SDK'sı ZIP dosyasında bulabilirsiniz:

  • NOTICE.txt
  • LICENSES.txt

Mobility veya Fleet Engine Deliveries müşterisiyseniz

Mobility veya Fleet Engine Deliveries müşterisiyseniz faturalandırma hakkında bilgi edinmek için Mobility belgelerini inceleyin. İşlemleri kaydetme hakkında daha fazla bilgi için Faturalandırmayı ayarlama, Faturalandırılabilir işlemleri kaydetme, Raporlama ve Faturalandırılabilir işlemleri kaydetme (Android) başlıklı makaleleri inceleyin.

Manuel bağımlılıklar (Gradle/Maven olmayan)

Derleme sisteminiz geçişli bağımlılıkları çözmüyorsa (ör. Bazel) veya AAR'yi manuel olarak entegre ediyorsanız bu bağımlılıkları projenize eklemeniz gerekir. Gradle ve Maven bunları otomatik olarak çözer.

  • androidx.datastore:datastore-core
  • androidx.datastore:datastore-guava
  • com.google.guava:listenablefuture
  • androidx.concurrent:concurrent-futures