Configura tu proyecto

En esta guía, se enumeran los requisitos de configuración de compilación para usar el SDK de Navigation para Android 5.0.0 y versiones posteriores.

Nota: Si tu proyecto usa el SDK de Navigation para Android sin usar la dependencia de Maven, disponible hasta la versión 4.99.2, sigue las instrucciones de configuración que se indican en Set up your project -- Version 4.99.2 and previous.

En las instrucciones, se supone que tienes instalado un IDE de Android y estás familiarizado con el desarrollo de Android.

Advertencia: A partir del SDK de Navigation (versión 5.0.0), la API ya no es compatible con Lollipop (4.4 a 5.1).

Requisitos mínimos para usar el SDK de Navigation

Estos requisitos se aplican a las versiones 5.0.0 y posteriores del SDK de Navigation para Android.

• Un proyecto de la consola de Google Cloud con el SDK de Navigation habilitado. Para el aprovisionamiento, comunícate con tu representante de Google Maps Platform.

• Tu app debe especificar versiones de Android de la siguiente manera:

  • La versión target debe ser Android 13 (nivel de API 33) o una posterior.
  • La versión mínima debe ser Android 6 (nivel de API 23) o una posterior.

• Para ejecutar una app compilada con el SDK de Navigation, el dispositivo Android debe cumplir con los siguientes requisitos:

  • Servicios de Google Play instalados y habilitados.

  • 2 GB de RAM o más

  • Compatibilidad con OpenGL ES 2.0 Consulta la documentación sobre la compatibilidad de código abierto de Android con Android 6.0 para la aceleración de gráficos 2D y 3D.

• Se deben agregar atribuciones y texto de licencia a la app.

Configura tus proyectos: proyecto de la consola de Cloud y proyecto de Android

Antes de compilar o probar una app, debes crear un proyecto de la consola de Cloud y agregar credenciales de clave de API. El proyecto debe tener aprovisionamiento para acceder al SDK de Navigation. Todas las claves dentro del proyecto de la consola de Cloud tienen el mismo acceso al SDK de Navigation. Una clave puede tener más de un proyecto de desarrollo asociado. Si ya tienes un proyecto de la consola, puedes agregar una clave a tu proyecto actual.

Información necesaria para configurar un proyecto

• El nombre de tu representante de Google Maps Platform
• Un nombre para tu proyecto de la consola de Cloud.
• Un nombre para tu proyecto de desarrollo de apps para Android que tiene un nombre de paquete que necesitarás más adelante.
• La huella digital del certificado SHA-1 de tu máquina de desarrollo.

Para configurar

1. En tu navegador web favorito, accede a la consola de Cloud y crea el proyecto de la consola de Cloud.
2. En tu IDE, como Android Studio, crea un proyecto de desarrollo de apps para Android y anota el nombre del paquete.
3. Comunícate con tu representante de Google Maps Platform para que te proporcione acceso al SDK de Navigation para tu proyecto de la consola de Cloud.
4. En el panel de Cloud Console en tu navegador web, crea credenciales para generar una clave de API con restricciones.
5. En la página Clave de API, haz clic en Apps para Android en el área Restricciones de aplicaciones.
6. Haz clic en Agregar el nombre del paquete y la huella digital y, luego, ingresa el nombre del paquete de tu proyecto de desarrollo y la huella digital SHA-1 para esa clave.
7. Haz clic en Guardar.

Agrega el SDK de Navigation a tu proyecto

El SDK de Navigation está disponible a través de Maven. Después de crear el proyecto de desarrollo, puedes integrar el SDK en él mediante uno de los siguientes enfoques.

Importante: Debes usar dependencias de Maven en tu proyecto para vincular el SDK de Navigation para Android.

Cómo usar Maven para el SDK de Navigation v4.5 y versiones posteriores (recomendado)

A continuación, se usa el repositorio de Maven google(), que es la forma más sencilla y recomendada de agregar el SDK de Navigation a tu proyecto.

Nota: Este método no es compatible con algunas bibliotecas que dependen del SDK de Navigation a través del ID del artefacto anterior. Esto incluye las versiones del SDK de Driver 4.4 o anteriores.

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

   Gradle

   Agrega lo siguiente a tu build.gradle a nivel de módulo:

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

   Si actualizas desde el repositorio de Maven original, ten en cuenta que los nombres de los grupos y los artefactos cambiaron y que ya no es necesario el complemento com.google.cloud.artifactregistry.gradle-plugin.

   Además, agrega lo siguiente a tu build.gradle de nivel superior:

   allprojects {
      ...
      // Required: you must exclude the Google Play service Maps SDK from
      // your transitive dependencies. This is to ensure 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>com.google.android.libraries.navigation</groupId>
       <artifactId>navigation</artifactId>
       <version>VERSION_NUMBER</version>
     </dependency>
   </dependencies>
   

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

   <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 una compilación correcta y un uso del SDK de Navigation.

Actualizar propiedades locales

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

Cómo actualizar 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. Además, considera configurar las opciones de optimización.

  Configuración obligatoria para el SDK de Navigation

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

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

  • Habilita la reducción de código y de recursos con R8/ProGuard para quitar el código y los recursos que no se usan 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: Configura resConfigs para un idioma durante el desarrollo. En la compilación final, configura resConfigs para los idiomas que realmente usas. De forma predeterminada, Gradle incluye cadenas de recursos para todos los idiomas compatibles con el SDK de Navigation.

  Cómo agregar la expansión de sintaxis para la compatibilidad con Java8

  • Si compilas tu app con el complemento de Android para Gradle 4.0.0 o una versión posterior, este extiende la compatibilidad para usar varias APIs del lenguaje Java 8. Consulta Compatibilidad con la expansión de sintaxis de Java 8 para obtener más información. Consulta el siguiente ejemplo de fragmento de secuencia de comandos de compilación para conocer las opciones de compilación y dependencia.

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 conocer los conjuntos de dependencias actualizados, ya que la versión del SDK de Navigation que usas puede estar un poco adelantada o retrasada con 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 33
        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:1.1.9'
}

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 más segura. No debes incluir la clave de API en el sistema de control de versión, por lo que te recomendamos almacenarla en el archivo secrets.properties, que se encuentra en el directorio raíz de tu proyecto. Para obtener más información sobre el archivo secrets.properties, consulta los archivos de propiedades de Gradle.

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

Nota: Consulta la documentación del complemento Secrets Gradle para Android en GitHub para conocer los requisitos del sistema y las instrucciones de instalación más recientes.

Si deseas instalar el complemento Secrets Gradle para Android en tu proyecto de Google Maps, haz lo siguiente:

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

   Groovy

   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. Abre el archivo build.gradle a nivel del módulo y agrega el siguiente código al elemento plugins.

   Groovy

   plugins {
       // ...
       id 'com.google.android.libraries.mapsplatform.secrets-gradle-plugin'
   }

   Kotlin

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

3. En tu archivo build.gradle a nivel del módulo, asegúrate de que targetSdk y compileSdk estén establecidos en 34.
4. Guarda el archivo y sincroniza tu proyecto con Gradle.
5. Abre el archivo secrets.properties en tu directorio de nivel superior y agrega el siguiente código. Reemplaza YOUR_API_KEY por tu clave de API. Almacena tu clave en este archivo, ya que secrets.properties no se registra en un sistema de control de versión.
   Nota: Si el archivo secrets.properties no existe, créalo en la misma carpeta en la que se encuentra el archivo local.properties.

   MAPS_API_KEY=YOUR_API_KEY

6. Guarda el archivo.

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

   Nota: Ingresa el código como se muestra. No reemplaces DEFAULT_API_KEY por tu clave de API.

   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.

8. Guarda el archivo.
9. En tu archivo AndroidManifest.xml, ve a com.google.android.geo.API_KEY y actualiza android:value attribute. Si la etiqueta <meta-data> no existe, créala como un elemento secundario de la etiqueta <application>.

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

Incluye las atribuciones requeridas en tu aplicación

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 como parte de la sección de avisos legales de tu app.

Punto clave: Para incluir las atribuciones, agrégalas como un elemento de menú independiente o como un elemento en un menú Acerca de.

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

• NOTICE.txt
• LICENSES.txt

Si eres cliente de entregas de movilidad o flotas de motor

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