Cómo agregar un mapa 3D a tu app

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 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 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 app 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 se debe establecer antes de que se inicialice el mapa. Para ello, configura Map.apiKey en el controlador de eventos init() de la View que contiene el mapa.

   Advertencia: No verifiques la clave de API en el control de código fuente externo o público

   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 en 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 de mapa.

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

   Nota: El orden de los parámetros es importante. La cámara se inicializa proporcionando primero la latitud y, luego, la longitud. Asegúrate de especificar los valores correctos para cada uno, en especial cuando los pegues desde otra fuente, o la cámara podría mostrar una ubicación inesperada.

   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 los siguientes parámetros:

• center: Es el LatLngAltitude que representa la ubicación de la cámara.
• heading: Es la orientación en grados desde el norte hacia donde se debe apuntar la cámara.
• tilt: Es el ángulo de inclinación en grados, donde 0 es directamente hacia abajo y 90 es hacia el horizonte.
• roll: Es el ángulo de rotación alrededor del plano vertical de la cámara, en grados.
• range: Es la distancia en metros de la cámara desde la ubicación de latitud y longitud.
• fieldOfView: Es 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.

Nota: También puedes ajustar la altitud relativa de la cámara con la inclinación y el rango.

Para que la vista de la cámara muestre más datos en 3D, establece los parámetros iniciales de modo que muestren 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 e 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 de Map:

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

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

Cómo escuchar eventos de presión en el mapa

Para escuchar eventos de presión en el mapa, aplica el modificador onTap(_:) a Map. Cuando un usuario presiona el mapa, el cierre recibe un valor MapTapInfo que proporciona el location (LatLngAltitude) y el content presionado (MapTapInfo.Content.map o MapTapInfo.Content.place(id:)). Para obtener más información sobre las interacciones con lugares de interés, consulta Cómo interactuar con lugares de interés.

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

¡Felicitaciones!

Agregaste correctamente un mapa en 3D a una app.

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