Adicionar análises a um componente do Kit de Interface do Places

Você pode se inscrever em eventos de análise sobre usuários que tocam em "Rotas", "Ligar" ou "Site", abrem o Google Maps, tocam na classificação por estrelas ou na atribuição de um autor, abrem o lightbox de fotos ou trocam de guia. Cada evento informa qual componente e tipo de conteúdo foi acionado, além do ID de lugar e do local.

Eventos do Analytics fornecidos

A tabela a seguir mostra exemplos de eventos de análise fornecidos pelo Kit de Interface do Places.

Interação com a interface tags: Set<String> Conteúdo associado/Tipo de conteúdo
Botão "Rotas" {"click", "directions", "outbound"} "main_action_button" ou "corner_action_button"
Botão "Abrir no Maps" {"click", "maps", "outbound"} "main_action_button" ou "corner_action_button"
Botão para chamadas / número de telefone (guia "Visão geral") {"click", "call_place", "outbound"} "phone_number", "main_action_button" ou "corner_action_button"
Botão para o site / Site (guia "Visão geral") {"click", "place_website", "outbound"} "website", "main_action_button" ou "corner_action_button"
Link de atribuição {"click", "attribution", "outbound"} "review" ou "media"
Link de classificação {"click", "reviews", "outbound"} "rating" ou "review_summaries"
Link da declaração legal (links da caixa de diálogo ⓘ) {"click", "disclosure", "outbound"} null (não configurável)
Link do relatório {"click", "report", "outbound"} "media", "review" ou "generative_summary"
Link da avaliação {"click", "review", "outbound"} "review"
Link de mídia / foto {"click", "media", "outbound"} "media"
Lightbox de fotos aberto (no app) {"click", "media"} "media"
Guia "Visão geral" selecionada (no app) {"click", "overview_tab"} null
Guia "Avaliações" selecionada (no app) {"click", "reviews_tab"} "review"
Guia "Sobre" selecionada (no app) {"click", "about_tab"} "features"
Menu flutuante de avaliações (⋮) aberto (no app) {"click", "reviews_menu"} "review"
Menu flutuante do Lightbox (⋮) aberto (no app) {"click", "lightbox_menu"} "media"
Menu de resumo generativo (⋮) aberto (no app) {"click", "generative_summary_menu"} "generative_summary"
Menu de resumo de avaliações generativas (⋮) aberto (no app) {"click", "review_summary_menu"} "review"

Como novos eventos e tags podem ser adicionados ao longo do tempo, é possível anexar um gerenciador genérico durante o desenvolvimento para registrar todos os eventos transmitidos conforme você interage com um 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...
}

Inscrever-se e processar eventos de análise

Para se inscrever em eventos de análise de um componente do Compose do UI Kit, envolva um contêiner de layout pai ou o próprio componente em ProvidePlacesAnalyticsHandler.

O código a seguir mostra como se inscrever e processar eventos de análise em uma hierarquia de contêineres:

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"}")
        }
      )
    }
  }
}

Se o app mostrar vários cards do mesmo tipo de widget (por exemplo, dois elementos combináveis AdvancedPlaceDetailsCompact), envolver cada elemento combinável no próprio ProvidePlacesAnalyticsHandler vai permitir que você saiba qual instância de card específica acionou o evento.

O snippet de código a seguir mostra como se inscrever e processar eventos de análise para um único elemento combinável 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"}")
      }
    )
  }
}

Adicionar e processar callbacks de toque no cartão

Os callbacks de toque no cartão precisam ser configurados e processados separadamente para cada componente do kit de interface.

Use o parâmetro onClick em um elemento combinável do Kit de Interface para processar toques no corpo do card. Quando o usuário toca no card, o onClick transmite um objeto Place preenchido com três propriedades:

  • place.id (String?): o ID de lugar exclusivo para, por exemplo, abrir uma visualização completa do Place Details ou selecionar um marcador.
  • place.location (LatLng?): as coordenadas de latitude/longitude do lugar para, por exemplo, centralizar uma câmera de mapa ou colocar um marcador.
  • place.viewport (LatLngBounds?): os limites recomendados da janela de visualização do mapa (coordenadas northeast e southwest) para enquadrar o lugar em um mapa.

O código a seguir mostra como adicionar e processar um callback de toque no card para um elemento combinável AdvancedPlaceDetailsCompact:

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}")
      }
    }
  )
}