Dodawanie statystyk do komponentu Places UI Kit

Możesz subskrybować zdarzenia analityczne dotyczące użytkowników, którzy klikają Wskazówki dojazdu, Zadzwoń lub Witryna, otwierają Mapy Google, klikają ocenę w gwiazdkach lub informacje o autorze, otwierają lightbox ze zdjęciem lub przełączają karty. Każde zdarzenie zawiera informacje o tym, który komponent i typ treści został uruchomiony, a także identyfikator miejsca i lokalizację.

Dostępne zdarzenia Analytics

W tabeli poniżej znajdziesz przykłady zdarzeń analitycznych udostępnianych przez Places UI Kit.

Interakcja z interfejsem tags: Set<String> Powiązane treści / typ treści
Przycisk umożliwiający wyznaczenie trasy {"click", "directions", "outbound"} "main_action_button" lub "corner_action_button"
Przycisk Otwórz w Mapach {"click", "maps", "outbound"} "main_action_button" lub "corner_action_button"
Przycisk połączenia / numer telefonu (karta Przegląd) {"click", "call_place", "outbound"} "phone_number", "main_action_button" lub "corner_action_button"
Przycisk witryny / Witryna (karta Przegląd) {"click", "place_website", "outbound"} "website", "main_action_button" lub "corner_action_button"
Link do atrybucji {"click", "attribution", "outbound"} "review" lub "media"
Link do oceny {"click", "reviews", "outbound"} "rating" lub "review_summaries"
Link do ujawnienia informacji (linki w oknie ⓘ) {"click", "disclosure", "outbound"} null (nie można konfigurować)
Link do raportu {"click", "report", "outbound"} "media", "review" lub "generative_summary"
Link do opinii {"click", "review", "outbound"} "review"
Link do multimediów/zdjęcia {"click", "media", "outbound"} "media"
Otwarto lightbox ze zdjęciem (w aplikacji) {"click", "media"} "media"
Wybrano kartę Przegląd (w aplikacji) {"click", "overview_tab"} null
Wybrano kartę Opinie (w aplikacji) {"click", "reviews_tab"} "review"
Wybrano kartę Informacje (w aplikacji) {"click", "about_tab"} "features"
Otwarto rozszerzone menu opinii (⋮) (w aplikacji) {"click", "reviews_menu"} "review"
Otwarto rozszerzone menu Lightbox (⋮) (w aplikacji) {"click", "lightbox_menu"} "media"
Otwarto menu podsumowania generatywnego (⋮) (w aplikacji) {"click", "generative_summary_menu"} "generative_summary"
Otwarto menu podsumowania opinii generatywnych (⋮) (w aplikacji) {"click", "review_summary_menu"} "review"

Z czasem mogą być dodawane nowe zdarzenia i tagi, dlatego podczas programowania możesz dołączyć ogólny moduł obsługi, aby rejestrować każde zdarzenie, które jest emitowane podczas interakcji z komponentem:

// 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...
}

Subskrybowanie i obsługa zdarzeń Analytics

Możesz subskrybować zdarzenia analityczne z komponentu UI Kit Compose, opakowując kontener układu nadrzędnego lub sam komponent w ProvidePlacesAnalyticsHandler.

Poniższy kod pokazuje, jak subskrybować i obsługiwać zdarzenia analityczne w hierarchii kontenerów:

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

Jeśli aplikacja wyświetla wiele kart tego samego typu widżetu (np. 2 funkcje kompozycyjne AdvancedPlaceDetailsCompact), umieszczenie każdej funkcji kompozycyjnej we własnym elemencie ProvidePlacesAnalyticsHandler pozwala dowiedzieć się, które konkretne wystąpienie karty wywołało zdarzenie.

Poniższy fragment kodu pokazuje, jak subskrybować i obsługiwać zdarzenia analityczne w przypadku pojedynczego elementu kompozycyjnego 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"}")
      }
    )
  }
}

Dodawanie i obsługa wywołań zwrotnych po kliknięciu karty

Wywołania zwrotne po kliknięciu karty muszą być skonfigurowane i obsługiwane osobno dla każdego komponentu UI Kit.

Użyj parametru onClick w funkcji kompozycyjnej UI Kit, aby obsługiwać kliknięcia treści karty. Gdy użytkownik kliknie kartę, onClick przekazuje obiekt Place z 3 właściwościami:

  • place.id (String?): unikalny identyfikator miejsca, który umożliwia np. otwarcie pełnego widoku informacji o miejscu lub wybranie znacznika.
  • place.location (LatLng?): współrzędne szerokości i długości geograficznej miejsca, np. do wyśrodkowania kamery mapy lub umieszczenia znacznika.
  • place.viewport (LatLngBounds?): zalecane granice widocznego obszaru mapy (współrzędne northeast i southwest) do wykadrowania miejsca na mapie.

Poniższy kod pokazuje, jak dodać i obsłużyć wywołanie zwrotne kliknięcia karty w przypadku funkcji kompozycyjnej 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}")
      }
    }
  )
}