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:

// Wrap your Places UI Kit composable or parent layout to inspect all broadcast events.
// AnalyticsEvent.toString() includes componentType, tags, place IDs, and contentType.
ProvidePlacesAnalyticsHandler(
  handler = { event ->
    Log.d("PlacesAnalytics", "$event")
  }
) {
  // Places UI Kit composables...
}

Suscríbete a eventos de Analytics y adminístralos

Puedes suscribirte a eventos de estadísticas desde un componente de Compose del kit de IU uniendo un contenedor de diseño de nivel superior o el componente en sí en ProvidePlacesAnalyticsHandler.

En el siguiente código, se muestra cómo suscribirse a los eventos de Analytics y controlarlos dentro de una jerarquía de contenedores:

import android.util.Log
import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.AnalyticsEvent
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.PlaceReference
import com.google.android.libraries.places.compose.ProvidePlacesAnalyticsHandler
import com.google.firebase.*

@Composable
fun PlaceCardScreen() {
  val placeRef = PlaceReference.PlaceId("ChIJN1t_tDeuEmsRUsoyG83frY4")

  // Analytics callback wraps the container hierarchy
  ProvidePlacesAnalyticsHandler(
    handler = { event ->
      val placeId = event.places.firstOrNull()?.id ?: "none"

      // Option A: Check for specific interactions using built-in Tags constants
      if (AnalyticsEvent.Tags.DIRECTIONS in event.tags) {
        Log.d("PlacesAnalytics", "User requested directions for place: $placeId")
      }

      if (AnalyticsEvent.Tags.OUTBOUND in event.tags) {
        Log.d(
          "PlacesAnalytics",
          "User is leaving the app via: ${event.tags.sorted().joinToString(", ")}"
        )
      }

      // Option B: Forward every event directly to your analytics SDK (e.g., Firebase)
      val firebaseAnalytics = remember { Firebase.analytics }
      firebaseAnalytics.logEvent("place_ui_kit_interaction") {
        param("component_type", event.componentType)
        param("content_type", event.contentType ?: "none")
        param("tags", event.tags.sorted().joinToString(","))
        param("place_id", placeId)
      }
    }
  ) {
    Column {
      AdvancedPlaceDetailsCompact(
        reference = placeRef,
        // Direct card tap (for UI navigation, e.g., centering a map)
        onClick = { place ->
          Log.d("Places", "Card tapped for place ID: ${place.id ?: "unknown"}")
        }
      )
    }
  }
}

Si tu app muestra varias tarjetas del mismo tipo de widget (por ejemplo, dos elementos de componibilidad AdvancedPlaceDetailsCompact), unir cada elemento de componibilidad en su propio ProvidePlacesAnalyticsHandler 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 estadísticas y controlarlos para una sola función de componibilidad AdvancedPlaceDetailsCompact:

import android.util.Log
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.AnalyticsEvent
import com.google.android.libraries.places.compose.Orientation
import com.google.android.libraries.places.compose.PlaceReference
import com.google.android.libraries.places.compose.ProvidePlacesAnalyticsHandler

@Composable
fun SinglePlaceCardView() {
  val placeRef = PlaceReference.PlaceId("ChIJN1t_tDeuEmsRUsoyG83frY4")

  // Analytics callback scoped to this specific composable instance
  ProvidePlacesAnalyticsHandler(
    handler = { event ->
      val placeIds = event.places.mapNotNull { it.id }.joinToString(", ")
      val tags = event.tags.sorted().joinToString(", ")

      Log.d(
        "PlacesAnalytics",
        "[$tags] in ${event.componentType}, content: ${event.contentType ?: "null"}, places: [$placeIds]"
      )

      if (AnalyticsEvent.Tags.DIRECTIONS in event.tags) {
        Log.d("PlacesAnalytics", "Directions tapped on this card")
      }
    }
  ) {
    AdvancedPlaceDetailsCompact(
      reference = placeRef,
      orientation = Orientation.HORIZONTAL,
      // Direct card-tap callback
      onClick = { place ->
        Log.d("Places", "Tapped card for place: ${place.id ?: "unknown"}")
      }
    )
  }
}

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 parámetro onClick en un elemento componible del kit de IU para controlar las presiones en el cuerpo de la tarjeta. Cuando el usuario presiona la tarjeta, onClick pasa un objeto Place propagado con tres propiedades:

  • place.id (String?): Es el ID de lugar único para, por ejemplo, abrir una vista completa de Place Details o seleccionar un marcador.
  • place.location (LatLng?): Son las coordenadas de latitud y longitud del lugar para, por ejemplo, centrar la cámara de un mapa o colocar un marcador.
  • place.viewport (LatLngBounds?): 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 elemento AdvancedPlaceDetailsCompact componible:

import android.util.Log
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import com.google.android.libraries.places.api.model.Place
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.Orientation
import com.google.android.libraries.places.compose.PlaceReference

@Composable
fun PlaceCardTapSampleView() {
  val peetsCoffeePlaceId = "ChIJT7FdmYiAhYAROFOvrIxRJDU"
  var selectedPlace by remember { mutableStateOf<Place?>(null) }

  AdvancedPlaceDetailsCompact(
    reference = PlaceReference.PlaceId(peetsCoffeePlaceId),
    orientation = Orientation.HORIZONTAL,
    onClick = { place ->
      // Handle the card tap using place.id, place.location, or place.viewport
      selectedPlace = place
      Log.d("Places", "Tapped place ID: ${place.id ?: "unknown"}")

      place.location?.let { location ->
        Log.d("Places", "Coordinates: ${location.latitude}, ${location.longitude}")
      }

      place.viewport?.let { viewport ->
        Log.d("Places", "Viewport NE: ${viewport.northeast}, SW: ${viewport.southwest}")
      }
    }
  )
}