Configuración

En esta página, se describe lo que debes hacer para configurar el SDK de Maps en 3D para Android y comenzar a compilar con él. El proceso de configuración implica configurar un proyecto de Google Cloud y una API para usarlos con el SDK y, luego, configurar un proyecto de Android Studio. Completa estos pasos antes de agregar tu primer mapa en 3D a tu app.

Requisitos previos

Para usar el SDK de Maps en 3D para Android, tu proyecto y los dispositivos de destino deben cumplir con los siguientes requisitos:

  • Nivel de API mínimo: nivel de API de Android 24 (Android 7.0) o posterior Tu app debe tener un minSdk de 24 o superior.
  • Servicios de Google Play: El SDK de Maps 3D para Android depende de los Servicios de Google Play. Los dispositivos de destino (y los emuladores con las APIs de Google) deben tener instalados los Servicios de Google Play.

Configura un proyecto de Google Cloud y una clave de API

Antes de comenzar a compilar con el SDK de Maps 3D para Android, debes configurar un proyecto de Google Cloud y una clave de API para usar con el SDK de Maps 3D para Android. Para ello, completa los siguientes pasos:

Paso 1: Configura tu proyecto

Console

  1. En la consola de Google Cloud, en la página del selector de proyectos, haz clic en Crear proyecto para comenzar a crear un proyecto nuevo de Cloud.

    Ir a la página Selector de proyectos

  2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud. Confirma que la facturación esté habilitada para tu proyecto.

    Google Cloud ofrece una prueba con un cargo de USD 0.00. La prueba vence al final de un plazo de 90 días, o bien después de que la cuenta acumule USD 300 en cargos, lo que ocurra primero. Puedes cancelar la prueba en cualquier momento. Para obtener más información, consulta Créditos de la cuenta de facturación y Facturación.

SDK de Cloud

gcloud projects create "PROJECT"

Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

Paso 2: Habilita las APIs o los SDKs

Para usar Google Maps Platform, debes habilitar las APIs o los SDKs que planeas usar con tu proyecto.

Ten en cuenta que algunas integraciones requieren que habilites varias API o SDK. Si no sabes qué API o SDK habilitar, prueba usar el Explorador de capacidades o consulta la documentación de la API o el SDK que quieres usar.

Para habilitar una o más APIs o SDKs, sigue estos pasos:

Console

  1. En la página Biblioteca de la API de Google Maps en la consola de Cloud, consulta las APIs y los SDKs de Google Maps Platform que puedes habilitar:

    Ve a la página Biblioteca de la API de Google Maps

  2. Haz clic en la API o el SDK que deseas habilitar.
    • Si el botón dice HABILITAR, haz clic en él para habilitar la API o el SDK.
    • Si el botón dice ADMINISTRAR, la API o el SDK ya están habilitados y no necesitas hacer nada más.
    • Si haces clic en cualquiera de los botones, se mostrará el panel de la API o el SDK. (Haz clic en el botón INHABILITAR para quitar la API o el SDK de este proyecto).

SDK de Cloud

El siguiente comando habilita todas las APIs de Maps, Routes y Places:

gcloud services enable \
    --project "PROJECT" \
    "addressvalidation.googleapis.com" \
    "areainsights.googleapis.com" \
    "tile.googleapis.com" \
    "aerialview.googleapis.com" \
    "elevation-backend.googleapis.com" \
    "routes.googleapis.com" \
    "geocoding-backend.googleapis.com" \
    "geolocation.googleapis.com" \
    "maps-android-backend.googleapis.com" \
    "maps-backend.googleapis.com" \
    "maps-embed-backend.googleapis.com" \
    "maps-ios-backend.googleapis.com" \
    "mapsplatformdatasets.googleapis.com" \
    "places-backend.googleapis.com" \
    "roads.googleapis.com" \
    "routeoptimization.googleapis.com" \
    "static-maps-backend.googleapis.com" \
    "street-view-image-backend.googleapis.com" \
    "timezone-backend.googleapis.com"

Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

Usa este comando para habilitar las APIs de entorno:

gcloud services enable \
    --project "PROJECT" \
    "airquality.googleapis.com" \
    "solar.googleapis.com" \
    "pollen.googleapis.com" \
    "weather.googleapis.com"

Paso 3: Obtén una clave de API

En este paso, solo se realiza el proceso de creación de la clave de API. Si usas la clave de API en producción, te recomendamos que la restrinjas. Puedes encontrar más información en la página Usar claves de API específica del producto.

La clave de API es un identificador único que se utiliza para autenticar solicitudes asociadas a tu proyecto con fines de uso y facturación. Debes tener, al menos, una clave de API asociada a tu proyecto. Para crear una clave nueva o agregar una API o un SDK a una clave existente, sigue estas instrucciones.

Console

  1. Ve a la página Google Maps Platform > Claves y credenciales.

    Ir a la página Claves y credenciales

  2. Si se solicita, selecciona tu proyecto.

  3. Realiza una de las siguientes acciones:

    • Crea una clave nueva:

      1. Haz clic en Crear credenciales > Clave de API.
      2. En el panel Crear clave de API, abre la lista Elige las restricciones de API.
      3. Borra las APIs que no necesite esta clave y asegúrate de que las APIs que planeas usar permanezcan seleccionadas.
      4. Haz clic en Crear. En el panel, se mostrará tu nueva clave de API.

    • Usar una clave existente:

      1. Haz clic en el nombre de la clave.
      2. En la lista Seleccionar las restricciones de API, selecciona las APIs que planeas usar.
      3. Haz clic en Guardar.

    Seleccionar una API aquí no la habilita. Asegúrate de que cada API que selecciones esté habilitada en la Biblioteca de APIs.

  4. Para ver la cadena de clave más adelante, ve a la página Claves y credenciales y haz clic en Mostrar clave para la clave.

Si la consola se ve diferente de estos pasos, consulta Crea una clave de API y Agrega restricciones de API en la documentación de Google Cloud.

SDK de Cloud

Reemplaza PROJECT_ID por el ID del proyecto en los siguientes comandos.

  • Crea una clave nueva: Ejecuta el siguiente comando y reemplaza DISPLAY_NAME por un nombre para la clave. Reemplaza SERVICE_NAME por el nombre del servicio de una API que planeas usar, como places.googleapis.com. Para permitir más APIs, repite la marca --api-target.

    gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=SERVICE_NAME

    Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

  • Usa una clave existente: Ejecuta el siguiente comando y reemplaza KEY_ID por el ID de la clave. Reemplaza SERVICE_NAME por el nombre del servicio de la API que deseas agregar. La marca --append conserva las APIs que la clave ya permite. Sin él, el comando las reemplaza.

    gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=SERVICE_NAME

    Obtén más información sobre el SDK de Google Cloud, la instalación del SDK de Cloud y los siguientes comandos:

    El ID de clave no es la cadena de clave ni el nombre visible. Para encontrarlo, ejecuta gcloud services api-keys list --project="PROJECT_ID". El ID es la última parte del campo name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

Para ver la cadena de la clave, ejecuta gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

Para habilitar el SDK, consulta la página SDK de Maps 3D para Android en la consola de Google Cloud. Para obtener más información sobre cómo completar estos pasos, consulta Cómo comenzar a utilizar Google Maps Platform.

Cómo configurar un proyecto de Android Studio

En esta sección, se explica cómo crear y configurar un proyecto de Android Studio para usarlo con el SDK de Maps en 3D para Android.

Parte 1: Configura tu proyecto y Gradle

  1. Crea un nuevo proyecto de Android Studio con la plantilla Empty Views Activity. En la configuración del proyecto, establece el SDK mínimo en la API 24 o una versión posterior.

  2. Si usas Git para el control de código fuente, modifica el archivo .gitignore del proyecto para evitar que el archivo de secretos se confirme en el control de versiones:

    • En el directorio raíz de tu proyecto, abre el archivo .gitignore.
    • Agrega la siguiente línea:
    secrets.properties

  3. Actualiza el archivo build.gradle.kts a nivel del proyecto:

    • En el directorio raíz de tu proyecto, abre el archivo build.gradle.kts.
    • En el bloque plugins, agrega el complemento Secrets Gradle:
    plugins {
  alias(libs.plugins.android.application) apply false
  alias(libs.plugins.kotlin.android) apply false
  alias(libs.plugins.secrets.gradle.plugin) apply false // Add this line
}

  4. Actualiza el archivo gradle/libs.versions.toml:

    • Abre el archivo gradle/libs.versions.toml, que suele encontrarse en el directorio gradle dentro del directorio raíz del proyecto.
    • En la sección [versions], agrega las versiones del SDK y del complemento de Secrets para Gradle:
    # See https://developers.google.com/android/guides/setup?device=phone-tablet for available releases
maps3dSdk = "16.0.1"
# See https://github.com/google/secrets-gradle-plugin/releases for available releases
secretsGradlePlugin = "2.0.1"
    • En la sección [library], agrega la biblioteca del SDK:
    play-services-maps3d = { module = "com.google.android.gms:play-services-maps3d", version.ref = "maps3dSdk" }
    • En la sección [plugins], agrega el complemento de Secrets para Gradle:
    secrets-gradle-plugin = { id = "com.google.android.libraries.mapsplatform.secrets-gradle-plugin", version.ref = "secretsGradlePlugin" }

  5. Actualiza el archivo app/build.gradle.kts a nivel del módulo:

    • Abre el archivo build.gradle.kts de nivel de módulo, que suele ubicarse en el directorio app.
    • En la parte superior del archivo, agrega el complemento de Gradle de Secrets al bloque plugins:
    plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.secrets.gradle.plugin) // Add this line
}
    • En el bloque dependencies, agrega la dependencia de los Servicios de Google Play para el SDK de Maps en 3D para Android:
    dependencies {
    // ... other dependencies
    implementation(libs.play.services.maps3d) // Add this line
}
    • Al final del archivo, fuera de los bloques android y dependencies, agrega la configuración de Secrets:
    secrets {
    // Optionally specify a different filename 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"
}

Parte 2: Agrega tu clave de API al proyecto

  1. Crea un archivo secrets.properties:

    • En el directorio raíz del módulo de la app (por lo general, el directorio app), crea un archivo nuevo llamado secrets.properties.
    • Agrega tu clave de API al archivo:
    MAPS3D_API_KEY=YOUR_API_KEY_HERE

  2. Crea un archivo local.defaults.properties: - En el directorio raíz del módulo de la app, crea un archivo nuevo llamado local.defaults.properties. - Agrega una clave de API predeterminada o de marcador de posición al archivo. Este archivo se puede verificar en el control de versiones:

    MAPS3D_API_KEY=DEFAULT_API_KEY_OR_PLACEHOLDER

Parte 3: Actualiza tu archivo AndroidManifest.xml

  1. Abre el archivo app/src/main/AndroidManifest.xml.

  2. Dentro de la etiqueta <application>, antes de la etiqueta <activity>, agrega el siguiente elemento <meta-data> para declarar tu clave de API:

    <application
    ...>

    <meta-data
        android:name="com.google.android.geo.maps3d.API_KEY"
        android:value="${MAPS3D_API_KEY}" />

    <activity
        ...>
    </activity>
</application>

    Durante el proceso de compilación, el complemento Secrets Gradle reemplazará el marcador de posición ${MAPS3D_API_KEY} por la clave de tu archivo secrets.properties.

Inicialización de la vista programática (opcional)

Si prefieres inicializar tu vista de mapa de manera programática en lugar de hacerlo en diseños XML, usa Map3DInitConfig.

import com.google.android.gms.maps3d.Map3DInitConfig
import com.google.android.gms.maps3d.Map3DView
import com.google.android.gms.maps3d.model.Map3DMode

// Set configuration options using the factory method
val config = Map3DInitConfig.create(
    mapMode = Map3DMode.HYBRID,
    centerLat = 38.544012,
    centerLng = -107.670428
)

val map3DView = Map3DView(context, config)

Próximos pasos

Ahora que tienes un proyecto de Google Cloud, una clave de API y un proyecto de Android Studio configurados para usarlos con el SDK de Maps en 3D para Android, puedes agregar un mapa en 3D a tu app.