Agrega estadísticas a un componente del kit de IU de Places

Puedes suscribirte a eventos de Analytics sobre los usuarios que presionan Cómo llegar, Llamar o Sitio web, abren Google Maps, presionan la calificación por estrellas o la atribución del autor, abren la ventana lightbox de fotos o cambian de pestaña. Cada evento indica qué componente y tipo de contenido se activaron, así como el ID de lugar y la ubicación.

Eventos de Analytics que se proporcionan

En la siguiente tabla, se proporcionan ejemplos de eventos de estadísticas que proporciona el kit de IU de Places.

Interacción con la IU tags: Set<String> Contenido asociado/Tipo de contenido
Botón Cómo llegar {"click", "directions", "outbound"} "main_action_button" o "corner_action_button"
Botón Abrir en Maps {"click", "maps", "outbound"} "main_action_button" o "corner_action_button"
Botón de llamada/número de teléfono (pestaña Resumen) {"click", "call_place", "outbound"} "phone_number", "main_action_button" o "corner_action_button"
Botón del sitio web/Sitio web (pestaña Resumen) {"click", "place_website", "outbound"} "website", "main_action_button" o "corner_action_button"
Vínculo de atribución {"click", "attribution", "outbound"} "review" o "media"
Vínculo de clasificación {"click", "reviews", "outbound"} "rating" o "review_summaries"
Vínculo de divulgación legal (vínculos del diálogo ⓘ) {"click", "disclosure", "outbound"} null (no configurable)
Vínculo del informe {"click", "report", "outbound"} "media", "review" o "generative_summary"
Vínculo para la revisión {"click", "review", "outbound"} "review"
Vínculo de contenido multimedia o foto {"click", "media", "outbound"} "media"
Se abrió la galería de fotos (en la app) {"click", "media"} "media"
Se seleccionó la pestaña Resumen (en la app) {"click", "overview_tab"} null
Se seleccionó la pestaña Opiniones (en la app) {"click", "reviews_tab"} "review"
Se seleccionó la pestaña Acerca de (en la app) {"click", "about_tab"} "features"
Se abrió el menú ampliado de opiniones (⋮) (en la app) {"click", "reviews_menu"} "review"
Se abrió el menú ampliado de Lightbox (⋮) (en la app) {"click", "lightbox_menu"} "media"
Se abrió el menú de resumen generativo (⋮) en la app {"click", "generative_summary_menu"} "generative_summary"
Se abrió el menú de resumen de opiniones generativo (⋮) (en la app) {"click", "review_summary_menu"} "review"

Como es posible que se agreguen eventos y etiquetas nuevos con el tiempo, puedes adjuntar un controlador genérico durante el desarrollo para registrar cada evento que se transmita a medida que interactúas con un componente:

// Attach to a Places UI Kit view or a parent container to inspect all broadcast events
.onPlaceAnalyticsEvent { event in
  print(
    "Analytics event — component: \(event.componentType), " +
    "tags: \(event.tags.sorted()), " +
    "content: \(event.contentType ?? "nil"), " +
    "places: \(event.places.compactMap(\.placeID))"
  )
}

Suscríbete a eventos de Analytics y adminístralos

Puedes suscribirte a los eventos de estadísticas desde un componente de UI Kit con el modificador onPlaceAnalyticsEvent. Puedes adjuntar el modificador a una vista de contenedor o directamente a un componente del kit de IU.

En el siguiente código, se muestra cómo suscribirse a los eventos de Analytics y controlarlos en una vista de contenedor:

import SwiftUI
import PlacesSwift

struct PlaceCardScreen: View {
  @State private var query = PlaceDetailsQuery(identifier: .placeID("ChIJN1t_tDeuEmsRUsoyG83frY4"))
  var configuration: PlaceDetailsCompactConfiguration {
    return PlaceDetailsCompactConfiguration(
      content: PlaceDetailsCompactView.standardContent,
      theme: PlacesMaterialTheme()
    )
  }

  var body: some View {
    VStack {
      PlaceDetailsCompactView(query: $query, configuration: configuration, placeDetailsCallback: { _ in })
        // 1. Direct card tap (for UI navigation, e.g., centering a map)
        .onTap { place in
          print("Card tapped for place ID: \(place.placeID ?? "unknown")")
        }
    }
    // 2. Analytics callback (can be attached to the card or any parent container)
    .onPlaceAnalyticsEvent { event in
      let placeID = event.places.first?.placeID ?? "none"

      // Option A: Check for specific interactions using built-in Tag constants
      if event.tags.contains(PlaceAnalyticsEvent.Tag.directions) {
        print("User requested directions for place: \(placeID)")
      }

      if event.tags.contains(PlaceAnalyticsEvent.Tag.outbound) {
        print("User is leaving the app via: \(event.tags.sorted().joined(separator: ", "))")
      }

      // Option B: Forward every event directly to your analytics SDK (e.g., Firebase)
      Analytics.logEvent("place_ui_kit_interaction", parameters: [
        "component_type": event.componentType,
        "content_type": event.contentType ?? "none",
        "tags": event.tags.sorted().joined(separator: ","),
        "place_id": placeID
      ])
    }
  }
}

Si tu app muestra varias tarjetas del mismo tipo de widget (por ejemplo, dos instancias de PlaceDetailsCompactView), adjuntar .onPlaceAnalyticsEvent directamente a cada vista te permite saber qué instancia de tarjeta específica activó el evento.

En el siguiente fragmento de código, se muestra cómo suscribirse a los eventos de Analytics y controlarlos directamente en un componente AdvancedPlaceDetailsCompactView:

import SwiftUI
import PlacesSwift

struct SinglePlaceCardView: View {
  @State private var query = PlaceDetailsQuery(
    identifier: .placeID("ChIJN1t_tDeuEmsRUsoyG83frY4")
  )
  private var configuration: AdvancedPlaceDetailsCompactConfiguration {
    AdvancedPlaceDetailsCompactConfiguration(
      content: AdvancedPlaceDetailsCompactView.standardContent,
      theme: PlacesMaterialTheme()
    )
  }

  var body: some View {
    AdvancedPlaceDetailsCompactView(
      orientation: .horizontal,
      query: $query,
      configuration: configuration
    ) { _ in }
      // 1. Direct card-tap callback (must come before generic `View` modifiers)
      .onTap { place in
        print("Tapped card for place: \(place.placeID ?? "unknown")")
      }
      // 2. Analytics callback scoped to this specific view instance
      .onPlaceAnalyticsEvent { event in
        let placeIDs = event.places.compactMap(\.placeID).joined(separator: ", ")
        let tags = event.tags.sorted().joined(separator: ", ")

        print("[\(tags)] in \(event.componentType), content: \(event.contentType ?? "nil"), places: [\(placeIDs)]")

        if event.tags.contains(PlaceAnalyticsEvent.Tag.directions) {
          print("Directions tapped on this card")
        }
      }
  }
}

Agrega y controla devoluciones de llamada de presión de tarjetas

Las devoluciones de llamada de presión de tarjetas se deben configurar y controlar por separado para cada componente del kit de IU.

Usa el modificador .onTap en un componente del kit de IU para controlar las presiones en el cuerpo de la tarjeta. Cuando el usuario presiona la tarjeta, .onTap pasa un struct Place propagado con tres propiedades:

  • place.placeID (String?): Es el ID de lugar único para, por ejemplo, abrir una hoja de PlaceDetailsView completa o seleccionar un marcador.
  • place.location (CLLocationCoordinate2D): Son las coordenadas de latitud y longitud del lugar para, por ejemplo, centrar la cámara de un mapa o colocar un marcador.
  • place.viewportInfo (RectangularCoordinateRegion?): Son los límites recomendados del viewport del mapa (coordenadas northEast y southWest) para enmarcar el lugar en un mapa.

En el siguiente código, se muestra cómo agregar y controlar una devolución de llamada de presión de tarjeta para un AdvancedPlaceDetailsCompactView:

import CoreLocation
import PlacesSwift
import SwiftUI

struct PlaceCardTapSampleView: View {
  static let peetsCoffeePlaceID = "ChIJT7FdmYiAhYAROFOvrIxRJDU"

  @State private var query = PlaceDetailsQuery(
    identifier: .placeID(peetsCoffeePlaceID)
  )
  @State private var selectedPlace: Place?

  var body: some View {
    AdvancedPlaceDetailsCompactView(
      orientation: .horizontal,
      query: $query,
      configuration: AdvancedPlaceDetailsCompactConfiguration(
        content: AdvancedPlaceDetailsCompactView.standardContent,
        theme: PlacesMaterialTheme()
      ),
      placeDetailsCallback: { _ in }
    )
    .onTap { place in
      // Handle the card tap using place.placeID, place.location, or place.viewportInfo
      selectedPlace = place
      print("Tapped place ID: \(place.placeID ?? "unknown")")
      print("Coordinates: \(place.location.latitude), \(place.location.longitude)")

      if let viewport = place.viewportInfo {
        print("Viewport NE: \(viewport.northEast), SW: \(viewport.southWest)")
      }
    }
  }
}