Aggiungi l'analisi a un componente di Places UI Kit

Puoi iscriverti agli eventi di analisi relativi agli utenti che toccano Indicazioni, Chiama o Sito web, aprono Google Maps, toccano la valutazione a stelle o l'attribuzione dell'autore, aprono il lightbox delle foto o cambiano scheda. Ogni evento indica il componente e il tipo di contenuto attivati, nonché l'ID luogo e la posizione.

Eventi Analytics forniti

La tabella seguente fornisce esempi di eventi di analisi forniti da Places UI Kit.

Interazione con la UI tags: Set<String> Contenuti associati/Tipo di contenuti
Pulsante Indicazioni stradali {"click", "directions", "outbound"} "main_action_button" o "corner_action_button"
Pulsante Apri in Maps {"click", "maps", "outbound"} "main_action_button" o "corner_action_button"
Pulsante Chiama/Numero di telefono (scheda Panoramica) {"click", "call_place", "outbound"} "phone_number", "main_action_button" o "corner_action_button"
Pulsante Sito web/Sito web (scheda Panoramica) {"click", "place_website", "outbound"} "website", "main_action_button" o "corner_action_button"
Link di attribuzione {"click", "attribution", "outbound"} "review" o "media"
Link alla valutazione {"click", "reviews", "outbound"} "rating" o "review_summaries"
Link alla divulgazione legale (link della finestra di dialogo ⓘ) {"click", "disclosure", "outbound"} null (non configurabile)
Link rapporto {"click", "report", "outbound"} "media", "review" o "generative_summary"
Link recensione {"click", "review", "outbound"} "review"
Link a contenuti multimediali/foto {"click", "media", "outbound"} "media"
Lightbox foto aperto (in-app) {"click", "media"} "media"
Scheda Panoramica selezionata (nell'app) {"click", "overview_tab"} null
Scheda Recensioni selezionata (in-app) {"click", "reviews_tab"} "review"
Scheda Informazioni selezionata (in-app) {"click", "about_tab"} "features"
Menu extra delle recensioni (⋮) aperto (in-app) {"click", "reviews_menu"} "review"
Menu extra lightbox (⋮) aperto (in-app) {"click", "lightbox_menu"} "media"
Menu del riepilogo generativo (⋮) aperto (nell'app) {"click", "generative_summary_menu"} "generative_summary"
Menu del riepilogo delle recensioni generativo (⋮) aperto (in-app) {"click", "review_summary_menu"} "review"

Poiché nel tempo potrebbero essere aggiunti nuovi eventi e tag, durante lo sviluppo puoi collegare un gestore generico per registrare ogni evento trasmesso mentre interagisci 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...
}

Iscriviti agli eventi di analisi e gestiscili

Puoi iscriverti agli eventi di analisi da un componente UI Kit Compose eseguendo il wrapping di un contenitore di layout principale o del componente stesso in ProvidePlacesAnalyticsHandler.

Il seguente codice mostra come iscriversi agli eventi di analisi e gestirli all'interno di una gerarchia di contenitori:

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 la tua app mostra più schede dello stesso tipo di widget (ad esempio, due componibili AdvancedPlaceDetailsCompact), l'aggregazione di ogni componibile nel proprio ProvidePlacesAnalyticsHandler ti consente di sapere quale istanza di scheda specifica ha attivato l'evento.

Il seguente snippet di codice mostra come iscriversi e gestire gli eventi di analisi per un singolo componibile 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"}")
      }
    )
  }
}

Aggiungi e gestisci i callback dei tocchi delle tessere

I callback dei tocchi delle schede devono essere configurati e gestiti separatamente per ogni componente di UI Kit.

Utilizza il parametro onClick su un composable UI Kit per gestire i tocchi sul corpo della scheda. Quando l'utente tocca la tessera, onClick passa un oggetto Place compilato con tre proprietà:

  • place.id (String?): l'ID luogo univoco, ad esempio per aprire una visualizzazione completa di Place Details o selezionare un indicatore.
  • place.location (LatLng?): le coordinate di latitudine/longitudine del luogo, ad esempio per centrare la fotocamera della mappa o posizionare un indicatore.
  • place.viewport (LatLngBounds?): i limiti consigliati per l'area visibile della mappa (coordinate northeast e southwest) per inquadrare il luogo su una mappa.

Il seguente codice mostra come aggiungere e gestire un callback di tocco della scheda per un elemento componibile 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}")
      }
    }
  )
}