Cómo configurar tu proyecto de Android Studio

En esta página, se explica cómo integrar el SDK de Navigation en tu proyecto de desarrollo.

Agrega el SDK de Navigation a tu proyecto

El SDK de Navigation está disponible a través del repositorio de Maven de Google. Puedes agregar el SDK a tu proyecto con la configuración de Gradle build.gradle o Maven pom.xml.

  1. Agrega la siguiente dependencia a tu configuración de Gradle o Maven, y sustituye el marcador de posición VERSION_NUMBER por la versión deseada del SDK de Navigation para Android.

    Gradle

    Agrega lo siguiente al archivo build.gradle a nivel del módulo:

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

    Maven

    Agrega lo siguiente a tu pom.xml:

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

  2. Si tienes dependencias que usan el SDK de Maps, debes excluir la dependencia en cada dependencia declarada que se base en el SDK de Maps.

    Gradle

    Agrega lo siguiente al archivo build.gradle de nivel superior:

    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

    Agrega lo siguiente a tu pom.xml:

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

Configura la compilación

Después de crear el proyecto, puedes establecer la configuración para compilar y usar correctamente el SDK de Navigation.

Actualiza las propiedades locales

  • En la carpeta Gradle Scripts, abre el archivo local.properties y agrega android.useDeprecatedNdk=true.

Actualiza la secuencia de comandos de compilación de Gradle

  • Abre el archivo build.gradle (Module:app) y usa los siguientes lineamientos para actualizar la configuración de modo que cumpla con los requisitos del SDK de Navigation. También considera establecer las opciones para optimizar.

    Configuración obligatoria para el SDK de Navigation

    1. Establece minSdkVersion en 24 o un valor superior.
    2. Establece targetSdkVersion en 36 o un valor superior.
    3. Agrega un parámetro de configuración dexOptions que aumente el javaMaxHeapSize.
    4. Establece la ubicación de las bibliotecas adicionales.
    5. Agrega el repositories y el dependencies para el SDK de Navigation.
    6. Reemplaza los números de versión de las dependencias por las versiones más recientes disponibles.

    Configuración opcional para reducir el tiempo de compilación

    • Habilita la reducción de código y recursos con R8 o ProGuard para quitar el código y los recursos sin usar de las dependencias. Si el paso de R8/ProGuard tarda demasiado en ejecutarse, considera habilitar multidex para el trabajo de desarrollo.
    • Reduce la cantidad de traducciones de idiomas incluidas en la compilación: Establece resConfigs para un idioma durante el desarrollo. Para la compilación final, establece resConfigs para los idiomas que realmente usas. De forma predeterminada, Gradle incluye cadenas de recursos para todos los idiomas que admite el SDK de Navigation.

    Agrega expansión de sintaxis para la compatibilidad con Java 8

    • Si compilas tu app con el complemento de Android para Gradle 4.0.0 o una versión posterior, el complemento extiende la compatibilidad para usar varias APIs del lenguaje Java 8. Para obtener más información, consulta Compatibilidad con la expansión de sintaxis de Java 8. Consulta el siguiente fragmento de secuencia de comandos de compilación de ejemplo para ver las opciones de compilación y dependencia.
    • Usa las versiones de Gradle, el complemento de Android para Gradle (AGP) y la biblioteca de expansión de sintaxis que coincidan con tu versión del SDK de Navigation. Consulta la tabla siguiente:
    • La biblioteca de expansión de sintaxis debe estar habilitada para el módulo app y cualquier módulo que dependa directamente del SDK de Navigation.

En la siguiente tabla, se enumeran las versiones de Gradle, AGP y la biblioteca de expansión de sintaxis necesarias para cada versión del SDK de Navigation.

Versión del SDK de Navigation Versión de Gradle Versión de AGP Biblioteca de expansión de sintaxis
8.0.0 y versiones posteriores 9.1.0 9.0.1 com.android.tools:desugar_jdk_libs_nio:2.1.5
7.7.0 a 7.9.0 8.13 8.13.2 com.android.tools:desugar_jdk_libs_nio:2.1.5
De la 7.3.0 a la 7.6.0 8.11.1 8.10.0 com.android.tools:desugar_jdk_libs_nio:2.0.3

A continuación, se muestra un ejemplo de la secuencia de comandos de compilación de Gradle para la aplicación. Consulta las apps de ejemplo para obtener conjuntos de dependencias actualizados, ya que la versión del SDK de Navigation que usas puede estar un poco más avanzada o retrasada con respecto a esta documentación.

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

Agrega la clave de API a tu app

En esta sección, se describe cómo almacenar tu clave de API para que tu app pueda hacer referencia a ella de manera segura. No debes incluir la clave de API en el sistema de control de versiones, por lo que te recomendamos almacenarla en un archivo secrets.properties en el directorio raíz de tu proyecto y excluir ese archivo del control de versiones. Para obtener más información sobre los archivos de propiedades de Gradle, consulta Archivos de propiedades de Gradle.

Para simplificar esta tarea, te recomendamos que uses el complemento Secrets Gradle para Android.

Para instalar el complemento Secrets Gradle para Android y almacenar tu clave de API, haz lo siguiente:

  1. En Android Studio, abre tu archivo build.gradle.kts o build.gradle de nivel superior y agrega el siguiente código al bloque plugins.

    Kotlin

    plugins {
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin") version "2.0.1" apply false
}

    Groovy

    plugins {
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin' version '2.0.1' apply false
}
  2. Abre el archivo build.gradle.kts o build.gradle a nivel del módulo y agrega el siguiente código al elemento plugins.

    Kotlin

    plugins {
    id("com.android.application")
    // ...
    id("com.google.android.libraries.mapsplatform.secrets-gradle-plugin")
}

    Groovy

    plugins {
    id 'com.android.application'
    // ...
    id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
}
  3. Si usas Android Studio, sincroniza tu proyecto con Gradle.
  4. Abre el archivo secrets.properties en tu directorio de nivel superior y, luego, agrega el siguiente código. Reemplaza YOUR_API_KEY por tu clave de API. Asegúrate de agregar secrets.properties a tu archivo .gitignore (o excluirlo de tu sistema de control de versiones) para no registrar tu clave de API en el control de versiones. 
    MAPS_API_KEY=YOUR_API_KEY

  5. Crea el archivo local.defaults.properties en tu directorio de nivel superior, en la misma carpeta en la que se encuentra el archivo secrets.properties, y agrega el siguiente código.

    MAPS_API_KEY=DEFAULT_API_KEY

    El propósito de este archivo es proporcionar una ubicación de copia de seguridad de la clave de API si no se encuentra el archivo secrets.properties, de modo que no fallen las compilaciones. Esto puede ocurrir si clonas la app desde un sistema de control de versión que omite secrets.properties y aún no creaste un archivo secrets.properties localmente para proporcionar tu clave de API.

  6. Puedes agregar la clave de API a tu archivo AndroidManifest.xml o proporcionarla de manera programática.
    • Agrega tu clave de API a AndroidManifest.xml: 
      <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${MAPS_API_KEY}" />

      Nota: com.google.android.geo.API_KEY es el nombre de metadatos recomendado para la clave de API. Se puede utilizar una clave con este nombre para autenticar varias APIs basadas en Google Maps en la plataforma de Android, incluido el SDK de Navigation para Android. Respecto de la retrocompatibilidad, la API también admite el nombre com.google.android.maps.v2.API_KEY. Este nombre heredado solo permite la autenticación con la versión 2 de la API de Google Maps para Android. Una aplicación puede especificar solo uno de los nombres de metadatos de la clave de API. Si se especifican ambos, la API arrojará una excepción.

    • Proporciona la clave de API de manera programática:

      El complemento Secrets Gradle hace que la clave esté disponible en la clase BuildConfig. En la inicialización de tu app (por ejemplo, en el método Application.onCreate()), llama al método de la siguiente manera:

      Kotlin

      1. Agrega las siguientes sentencias de importación: 
        import com.google.android.libraries.navigation.NavigationApi
      2. Agrega lo siguiente a tu método Application.onCreate(): 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY)

      Java

      1. Agrega las siguientes sentencias de importación: 
        import com.google.android.libraries.navigation.NavigationApi;
      2. Agrega lo siguiente a tu método Application.onCreate(): 
        NavigationApi.setApiKey(BuildConfig.MAPS_API_KEY);
      Nota: Cuando uses setApiKey(), ten en cuenta lo siguiente:
      • Proporciona una clave de API que no sea nula ni esté vacía.
      • Llama a setApiKey() solo una vez durante el ciclo de vida de tu aplicación. El método arroja un IllegalStateException si se lo llama más de una vez.
      • Llama a setApiKey() antes de inicializar cualquier otro componente del SDK de Navigation, como Navigator.
      • La clave que proporciones con este método anulará cualquier clave de API en tu AndroidManifest.xml.
      • Usa la versión 7.6 o posterior del SDK de Navigation.

  7. En Android Studio, abre el archivo build.gradle.kts o build.gradle a nivel del módulo y edita la propiedad secrets. Si la propiedad secrets no existe, agrégala.

    Edita las propiedades del complemento para establecer propertiesFileName en "secrets.properties", establecer defaultPropertiesFileName en "local.defaults.properties" y establecer cualquier otra propiedad.

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

    Groovy

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

Incluye las atribuciones obligatorias en tu app

Si usas el SDK de Navigation para Android en tu app, debes incluir el texto de atribución y las licencias de código abierto en la sección de avisos legales de la app.

Puedes encontrar el texto de atribución requerido y las licencias de código abierto en el archivo ZIP del SDK de Navigation para Android:

  • NOTICE.txt
  • LICENSES.txt

Si eres cliente de Mobility o de Fleet Engine Deliveries

Si eres cliente de Mobility o de Fleet Engine Deliveries, obtén información sobre la facturación en la documentación de Mobility. Para obtener más información sobre cómo registrar transacciones, consulta Configura la facturación, Registra transacciones facturables, Informes y Registra transacciones facturables (Android).

Dependencias manuales (que no son de Gradle ni Maven)

Si tu sistema de compilación no resuelve las dependencias transitivas (como Bazel) o si integras el AAR de forma manual, debes agregar estas dependencias a tu proyecto. Gradle y Maven las resuelven automáticamente.

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