Cómo agregar un mapa 3D a tu app

Este producto o función está en versión experimental (fase previa a la DG). Los productos y las funciones que se encuentran en la fase previa a la DG pueden tener asistencia limitada, y los cambios en estos productos y funciones podrían no ser compatibles con otras versiones de la fase previa a la DG. Las ofertas que se encuentran en la fase previa a la DG se rigen por las Condiciones Específicas del Servicio de Google Maps Platform. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Selecciona la plataforma: Android iOS JavaScript

En esta página, se explica con un ejemplo cómo agregar un mapa 3D básico a una app para Android con el SDK de Maps 3D para Android. En las instrucciones de esta página, se da por sentado que ya completaste los pasos de la página Configuración y que tienes lo siguiente:

• Un proyecto de Google Cloud con el SDK de Maps 3D para Android habilitado
• Una clave de API configurada para usar con el SDK de Mapas 3D para Android
• Un proyecto de Android Studio configurado para usar con el SDK de Mapas 3D para Android

Para obtener más información sobre estos requisitos previos, consulta Configuración.

Parte 1: Actualiza el archivo de diseño (activity_main.xml) para agregar el componente Map3DView

El componente Map3DView es la vista que renderiza el mapa en 3D dentro de la app. En los siguientes pasos, se agrega el componente y se configura el estado inicial del mapa, incluida la posición de la cámara y los atributos relacionados:

Nota: En los pasos de esta sección, se supone que creaste y configuraste tu proyecto de Android Studio con el proceso que se describe en Configuración, o que agregaste una nueva actividad de View a un proyecto existente. Si creas un proyecto nuevo de Android Studio sin agregar una actividad de View, tu proyecto no contendrá un archivo activity_main.xml.

1. Abre el archivo de diseño de tu actividad principal, que normalmente se encuentra en app/src/main/res/layout/activity_main.xml.

2. En el elemento raíz ConstraintLayout (o tu elemento de diseño raíz), agrega el espacio de nombres XML map3d:

   xmlns:map3d="http://schemas.android.com/apk/res-auto"
   

3. Elimine el <TextView> predeterminado que muestra "¡Hola mundo!".

4. Agrega el componente Map3DView a tu diseño. Puedes personalizar la posición de la cámara y otros atributos:

   <?xml version="1.0" encoding="utf-8"?>
   <androidx.constraintlayout.widget.ConstraintLayout xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:app="http://schemas.android.com/apk/res-auto"
     xmlns:map3d="http://schemas.android.com/apk/res-auto" xmlns:tools="http://schemas.android.com/tools"
     android:id="@+id/main"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
     tools:context=".MainActivity">
   
     <com.google.android.gms.maps3d.Map3DView
       android:id="@+id/map3dView"
       android:layout_width="match_parent"
       android:layout_height="match_parent"
       map3d:mode="hybrid"
       map3d:centerLat="38.544012"
       map3d:centerLng="-107.670428"
       map3d:centerAlt="2427.6"
       map3d:heading="310"
       map3d:tilt="63"
       map3d:range="8266"
       map3d:roll="0"
       map3d:minAltitude="0"
       map3d:maxAltitude="1000000"
       map3d:minHeading="0"
       map3d:maxHeading="360"
       map3d:minTilt="0"
       map3d:maxTilt="90"
       app:layout_constraintBottom_toBottomOf="parent"
       app:layout_constraintEnd_toEndOf="parent"
       app:layout_constraintStart_toStartOf="parent"
       app:layout_constraintTop_toTopOf="parent" />
   </androidx.constraintlayout.widget.ConstraintLayout>
   

Parte 2: Actualizar MainActivity.kt

Los siguientes pasos inicializan el componente Map3DView agregado al archivo activity_main.xml en la Parte 1 y gestionan los eventos del ciclo de vida del componente:

1. Abre tu archivo MainActivity.kt, que normalmente se encuentra en app/src/main/java/com/example/yourpackagename/MainActivity.kt.

2. Agrega las importaciones necesarias para el SDK de Maps 3D para Android:

   import com.google.android.gms.maps3d.GoogleMap3D
   import com.google.android.gms.maps3d.Map3DView
   import com.google.android.gms.maps3d.OnMap3DViewReadyCallback
   

3. Modifique la clase MainActivity para que implemente OnMap3DViewReadyCallback:

   class MainActivity : AppCompatActivity(), OnMap3DViewReadyCallback {
   

4. Declara variables para Map3DView y GoogleMap3D:

   private lateinit var map3DView: Map3DView
   private var googleMap3D: GoogleMap3D? = null
   

5. En el método onCreate, después de setContentView(...) y el bloque ViewCompat.setOnApplyWindowInsetsListener, inicialice el map3DView, llame a su método de ciclo de vida onCreate y solicite el mapa de forma asíncrona:

   override fun onCreate(savedInstanceState: Bundle?) {
       super.onCreate(savedInstanceState)
       enableEdgeToEdge()
       setContentView(R.layout.activity_main)
       ViewCompat.setOnApplyWindowInsetsListener(findViewById(R.id.main)) { v, insets ->
           val systemBars = insets.getInsets(WindowInsetsCompat.Type.systemBars())
           v.setPadding(systemBars.left, systemBars.top, systemBars.right, systemBars.bottom)
           insets
       }
   
       map3DView = findViewById(R.id.map3dView)
       map3DView.onCreate(savedInstanceState)
       map3DView.getMap3DViewAsync(this)
   }
   

6. Anula el método onMap3DViewReady. Esta función de devolución de llamada se activa cuando el mapa está listo para ser utilizado:

   override fun onMap3DViewReady(googleMap3D: GoogleMap3D) {
       // Interact with the googleMap3D object here
       this.googleMap3D = googleMap3D
       // You can now make calls to the googleMap3D object, e.g.,
       // googleMap3D.cameraController.flyTo(camera { ... })
   }
   

7. Reenvía los eventos de ciclo de vida de tu Activity al Map3DView agregando las siguientes anulaciones al MainActivity:

   override fun onStart() {
       super.onStart()
       map3DView.onStart()
   }
   
   override fun onResume() {
       super.onResume()
       map3DView.onResume()
   }
   
   override fun onPause() {
       map3DView.onPause()
       super.onPause()
   }
   
   override fun onStop() {
       map3DView.onStop()
       super.onStop()
   }
   
   override fun onDestroy() {
       map3DView.onDestroy()
       super.onDestroy()
   }
   
   override fun onSaveInstanceState(outState: Bundle) {
       super.onSaveInstanceState(outState)
       map3DView.onSaveInstanceState(outState)
   }
   
   override fun onLowMemory() {
       super.onLowMemory()
       map3DView.onLowMemory()
   }
   

Parte 3: Sincronizar Gradle y ejecutar

Ahora que has actualizado el diseño y la actividad de tu aplicación, puedes compilarla y ejecutarla para ver la vista del mapa en 3D.

1. Para sincronizar tu proyecto con Gradle, selecciona Archivo > Sincronizar proyecto con archivos Gradle.

2. Para compilar y ejecutar tu app en un emulador o un dispositivo físico, selecciona Run > Run.

Si todo está configurado correctamente, debería ver un mapa 3D mostrado en su aplicación, centrado cerca de las coordenadas especificadas en su activity_main.xml.

Próximos pasos

Ahora que agregaste un mapa 3D básico a tu app, puedes explorar funciones más avanzadas del SDK de Maps 3D para Android, como animaciones de rutas de cámara, marcadores 3D o polígonos.