Cómo agregar un mapa 3D a tu app

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

• Un proyecto de Google Cloud con el SDK de Maps 3D para iOS habilitado
• Una clave de API para el SDK de Maps 3D para iOS
• Xcode versión 16.0 o posterior con el paquete del SDK de Maps 3D para iOS agregado.

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

Sigue un codelab más avanzado.

Consulta más muestras de código en GitHub.

Parte 1: Crea una app básica de SwiftUI

1. Crea una aplicación nueva en Xcode.
2. Establece el Nombre del producto en Hello3DWorld, con el identificador de la organización establecido en com.example. El nombre del paquete debe ser com.example.Hello3DWorld.
3. Elige la interfaz de SwiftUI.
4. Agrega la biblioteca de Maps 3D a tu app. Consulta las instrucciones en la sección de configuración.

Parte 2: Agrega un mapa

1. Abre el archivo llamado ContentView.swift. Este es el punto de entrada y la navegación principal de tu app.

2. Importa SwiftUI y el paquete GoogleMaps3D.

3. Reemplaza todo el código dentro de la declaración del cuerpo por Map(mode: .hybrid).

   La configuración inicial mínima que debes proporcionar para inicializar un Map es el MapMode:

   • .hybrid,
   • .roadmap o
   • .satellite

   Tu archivo ContentView.swift debería tener el siguiente aspecto:

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     var body: some View {
       Map(mode: .hybrid)
     }
   }
   
   #Preview {
     ContentView()
   }
   

Parte 3: Establece tu clave de API

1. La clave de API debe establecerse antes de que se inicialice el mapa. Para ello, establece Map.apiKey en el controlador de eventos init() de la View que contiene el mapa.

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
   
     var body: some View {
       Map(mode: .hybrid)
     }
   }
   

Parte 4: Usa una cámara para controlar la vista del mapa

Las vistas de mapas 3D se controlan con la clase Camera. En este paso, aprenderás a especificar la ubicación, la altitud, el rumbo, la inclinación, el giro y el rango para personalizar la vista del mapa.

1. Cambia la llamada a función Map() para incluir una propiedad initialCamera. Inicializa initialCamera para mostrar una vista del centro de Manhattan.

   import SwiftUI
   import GoogleMaps3D
   
   struct ContentView: View {
     init () {
       Map.apiKey = "YOUR_API_KEY"
     }
     var body: some View {
       Map(initialCamera: .init(
         center: .init(latitude: 40.748339, longitude: -73.985912, altitude: 211.1),
         heading: 52,
         tilt: 68,
         roll: 0.0,
         range: 1039,
         fieldOfView: .degrees(50)
       ), mode: .hybrid)
     }
   }
   

El código anterior establece valores para estos parámetros:

• center: El LatLngAltitude que representa la ubicación de la cámara
• heading: El rumbo en grados desde el norte para apuntar la cámara hacia.
• tilt: El ángulo de inclinación en grados, donde 0 es directamente sobre la cabeza y 90 es horizontal.
• roll: El ángulo de giro alrededor del plano vertical de la cámara, en grados.
• range: La distancia en metros de la cámara desde la ubicación de latitud y longitud
• fieldOfView: El ángulo que representa el campo visual de la cámara

Si no proporcionas ninguno de estos parámetros adicionales, se usará un valor predeterminado.

Para que la vista de la cámara muestre más datos 3D, establece los parámetros iniciales para mostrar una vista más cercana e inclinada.

Parte 5: Obtén una vista previa de tu app y ejecútala

1. Agrega una vista previa de Xcode

   Las vistas previas son una potente función de Xcode que te permite ver tu app y, también, interactuar con ella sin tener que usar el simulador ni un dispositivo externo.

   Para agregar una vista previa, agrega un bloque de código #Preview {} fuera de tu struct.

   #Preview {
     ContentView()
   }
   

2. Ejecuta la app

Compila y ejecuta la app.

Estados de carga y error del mapa

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

• Superposición de carga: Se muestra un indicador de progreso centrado cuando se inicializa o carga la vista del mapa por primera vez.
• Superposición de error: Se muestra una superposición de error si no se carga el mapa.

Si aplicas un diseño de mapa basado en Cloud con style(mapID:error:) en Map, puedes pasar un cierre error para controlar los errores de carga de diseño.

Escucha los eventos de toque del mapa

Para escuchar los eventos de toque en el mapa, aplica el onTap(_:) modificador a Map. Cuando un usuario toca el mapa, el cierre recibe un MapTapInfo valor que proporciona la location (LatLngAltitude) y el content tocado (MapTapInfo.Content.map o MapTapInfo.Content.place(id:)). Para obtener más información sobre las interacciones con los lugares de interés, consulta Interactúa con los lugares de interés.

Map(mode: .hybrid)
  .onTap { tapInfo in
    print("Tapped at \(tapInfo.location), content: \(tapInfo.content)")
  }

¡Felicitaciones!

Agregaste correctamente un mapa 3D a una app.

A continuación, puedes explorar funciones más avanzadas del SDK de Maps 3D para iOS, como animaciones de ruta de cámara, marcadores 3D o polígonos.