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 supone que ya completaste los pasos de la configuración página 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 Maps 3D para Android
• Un proyecto de Android Studio configurado para usar con el SDK de Maps 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 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 descrito 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 suele ubicarse en app/src/main/res/layout/activity_main.xml.

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

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

3. Borra el <TextView> predeterminado que muestra "Hello World!".

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:mode="hybrid"
       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: Actualiza MainActivity.kt

En los siguientes pasos, se inicializa el componente Map3DView que se agregó al archivo activity_main.xml en la Parte 1 y se administran los eventos del ciclo de vida del componente.

Ten en cuenta que el SDK de Maps 3D para Android solo admite una instancia Map3DView activa a la vez. No se admite mostrar varias instancias de Map3DView simultáneamente (p.ej., en el mismo diseño o en diferentes actividades o fragmentos visibles), y esto puede generar problemas de renderización, como pantallas negras en vistas secundarias.

Además, todos los Map3DView compartirán y reflejarán el mismo estado del mapa (p. ej., posición de la cámara, marcadores agregados, polígonos, etcétera), que persistirá incluso si se destruye un Map3DView (con onDestroy) y se crea otro, a menos que se borre de forma manual. Por ejemplo, si agregas marcadores a Map3DView1, luego lo destruyes y creas Map3DView2, esos mismos marcadores seguirán presentes en Map3DView2.

Responsabilidades del desarrollador:

• Una vista a la vez: Asegúrate de que solo un Map3DView esté en una parte activa de tu jerarquía de vistas en cualquier momento.
• Limpieza manual: Cuando cambies de un Map3DView (p.ej., Map3DView1) a otro (p.ej., Map3DView2), debes llamar a onDestroy() en la instancia anterior (Map3DView1). Debido a que el estado del mapa subyacente se comparte, para asegurarte de que Map3DView2 comience con un estado nuevo o específico, eres responsable de borrar manualmente cualquier estado establecido por Map3DView1. Esto incluye quitar marcadores, superposiciones, etcétera, y restablecer la posición de la cámara con el objeto GoogleMap3D obtenido en OnMap3DViewReadyCallback.

1. Abre el archivo MainActivity.kt, que suele ubicarse en app/src/main/java/com/example/yourpackagename/MainActivity.kt.

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

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

3. Modifica la clase MainActivity para implementar 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, inicializa map3DView, llama a su método de ciclo de vida onCreate y solicita 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 los métodos onMap3DViewReady y onError. Estas devoluciones de llamada se activan cuando el mapa está listo para usarse o cuando se produce un error durante la inicialización:

   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 { ... })
   }
   
   override fun onError(error: Exception) {
       // Handle the error gracefully here (for example, show an error dialog or log the error).
       Log.e("MainActivity", "Error loading 3D map", error)
   }
   

7. Reenvía los eventos del ciclo de vida de tu actividad a Map3DView agregando las siguientes anulaciones a 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: Sincroniza Gradle y ejecuta

Ahora que actualizaste el diseño y la actividad de tu app, puedes compilar y ejecutar la app para ver la vista del mapa 3D.

1. Para sincronizar tu proyecto con Gradle, selecciona File > Sync Project with Gradle Files.

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

Si todo está configurado correctamente, deberías ver un mapa 3D que se muestra en tu app, centrado cerca de las coordenadas especificadas en activity_main.xml.

Estados de carga y error del mapa

El SDK de Maps 3D para Android muestra automáticamente comentarios visuales integrados mientras administra el estado del mapa:

• Superposición de carga: Se muestra un indicador de progreso centrado cuando se inicializa por primera vez la vista del mapa o se carga su viewport inicial.
• Superposición de error: Se muestra una tarjeta de error con estilo si se produce una falla crítica, como una clave de API no válida, un error de red o cuando se ejecuta en un dispositivo no compatible.

Puedes capturar estos errores de inicialización o carga de forma programática mediante la anulación de onError(error: Exception) dentro de tu OnMap3DViewReadyCallback implementación.

Escucha los eventos de clic en el mapa

Para escuchar los eventos de clic en el mapa, usa GoogleMap3D.setMap3DClickListener. Este objeto de escucha se activa cuando un usuario hace clic en el mapa y proporciona la ubicación y el ID de lugar del punto seleccionado.

En el siguiente ejemplo, se muestra cómo configurar un objeto de escucha de clic en el mapa:

googleMap3D.setMap3DClickListener { location, placeId ->
    lifecycleScope.launch(Dispatchers.Main) {
        if (placeId != null) {
            Toast.makeText(this@MainActivity, "Clicked on place with ID: $placeId", Toast.LENGTH_SHORT).show()
        } else {
            Toast.makeText(this@MainActivity, "Clicked on location: $location", Toast.LENGTH_SHORT).show()
        }
    }
}

Ten en cuenta que el controlador de clics no se ejecuta en el subproceso principal (o de IU). Si deseas realizar cambios en la IU (como mostrar un mensaje de Toast), debes cambiar al subproceso principal. En Kotlin, puedes hacerlo con lifecycleScope.launch(Dispatchers.Main).

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 ruta de cámara, marcadores 3D o polígonos.