Cómo agregar un mapa 3D a tu app

Selecciona la plataforma: Android iOS JavaScript

Un mapa en 3D que muestra la ciudad de Nueva York

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:

  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 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. 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: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 agregado al archivo activity_main.xml en la Parte 1 y se administran los eventos del ciclo de vida del componente:

  1. Abre el archivo MainActivity.kt, que suele estar ubicado 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. 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 el método onMap3DViewReady. Esta devolución de llamada se activa cuando el mapa está listo para usarse:

    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 del ciclo de vida de tu Activity a Map3DView agregando los siguientes reemplazos 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 la app

Ahora que actualizaste el diseño y la actividad de tu app, puedes compilar y ejecutar la app para ver la vista del mapa en 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 en 3D en tu app, centrado cerca de las coordenadas especificadas en tu 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.

Cómo detectar eventos de clic en el mapa

Para escuchar 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 en el que se hizo clic.

En el siguiente ejemplo, se muestra cómo configurar un objeto de escucha de clics 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 (por ejemplo, mostrar un mensaje Toast), debes cambiar al subproceso principal. En Kotlin, puedes hacerlo con lifecycleScope.launch(Dispatchers.Main).