Ajouter des analyses à un composant du Kit UI pour Places

Vous pouvez vous abonner aux événements d'analyse concernant les utilisateurs qui appuient sur "Itinéraire", "Appeler" ou "Site Web", ouvrent Google Maps, appuient sur la note ou l'attribution de l'auteur, ouvrent la visionneuse de photos ou changent d'onglet. Chaque événement indique le composant et le type de contenu qui ont été déclenchés, ainsi que l'ID de lieu et l'emplacement.

Événements Analytics fournis

Le tableau suivant fournit des exemples d'événements d'analyse fournis par le Kit UI pour Places.

Interaction avec l'UI tags: Set<String> Contenu associé/Type de contenu
Bouton "Itinéraire" {"click", "directions", "outbound"} "main_action_button" ou "corner_action_button"
Bouton "Ouvrir dans Maps" {"click", "maps", "outbound"} "main_action_button" ou "corner_action_button"
Bouton d'appel/Numéro de téléphone (onglet "Aperçu") {"click", "call_place", "outbound"} "phone_number", "main_action_button" ou "corner_action_button"
Bouton "Site Web"/Site Web (onglet "Aperçu") {"click", "place_website", "outbound"} "website", "main_action_button" ou "corner_action_button"
Lien d'attribution {"click", "attribution", "outbound"} "review" ou "media"
Lien d'évaluation {"click", "reviews", "outbound"} "rating" ou "review_summaries"
Lien vers les mentions légales (liens de la boîte de dialogue ⓘ) {"click", "disclosure", "outbound"} null (non configurable)
Lien vers le rapport {"click", "report", "outbound"} "media", "review" ou "generative_summary"
Lien d'avis {"click", "review", "outbound"} "review"
Lien vers le média/la photo {"click", "media", "outbound"} "media"
Lightbox de photo ouverte (dans l'application) {"click", "media"} "media"
Onglet "Aperçu" sélectionné (dans l'application) {"click", "overview_tab"} null
Onglet "Avis" sélectionné (dans l'application) {"click", "reviews_tab"} "review"
Onglet "À propos" sélectionné (dans l'application) {"click", "about_tab"} "features"
Menu à développer des avis (⋮) ouvert (dans l'application) {"click", "reviews_menu"} "review"
Menu à développer Lightbox (⋮) ouvert (dans l'application) {"click", "lightbox_menu"} "media"
Menu "Résumé génératif" (⋮) ouvert (dans l'application) {"click", "generative_summary_menu"} "generative_summary"
Menu du résumé des avis génératif (⋮) ouvert (dans l'application) {"click", "review_summary_menu"} "review"

Étant donné que de nouveaux événements et tags peuvent être ajoutés au fil du temps, vous pouvez associer un gestionnaire générique pendant le développement pour consigner chaque événement diffusé lorsque vous interagissez avec un composant :

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

S'abonner aux événements d'analyse et les gérer

Vous pouvez vous abonner aux événements d'analyse d'un composant Compose du kit d'interface utilisateur en encapsulant un conteneur de mise en page parent ou le composant lui-même dans ProvidePlacesAnalyticsHandler.

Le code suivant montre comment s'abonner aux événements d'analyse et les gérer dans une hiérarchie de conteneurs :

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 votre application affiche plusieurs fiches du même type de widget (par exemple, deux composables AdvancedPlaceDetailsCompact), encapsuler chaque composable dans son propre ProvidePlacesAnalyticsHandler vous permet de savoir quelle instance de fiche spécifique a déclenché l'événement.

L'extrait de code suivant montre comment s'abonner aux événements d'analyse et les gérer pour un seul composable 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"}")
      }
    )
  }
}

Ajouter et gérer des rappels d'appui sur une carte

Les rappels de pression sur une carte doivent être configurés et gérés séparément pour chaque composant du kit d'interface utilisateur.

Utilisez le paramètre onClick sur un composable du kit d'interface utilisateur pour gérer les appuis sur le corps de la fiche. Lorsque l'utilisateur appuie sur la carte, onClick transmet un objet Place contenant trois propriétés :

  • place.id (String?) : ID de lieu unique permettant, par exemple, d'ouvrir une vue complète des Place Details d'un lieu ou de sélectionner un repère.
  • place.location (LatLng?) : coordonnées de latitude/longitude du lieu, par exemple pour centrer la caméra de la carte ou placer un repère.
  • place.viewport (LatLngBounds?) : limites de la fenêtre d'affichage de la carte recommandées (coordonnées northeast et southwest) pour cadrer le lieu sur une carte.

Le code suivant montre comment ajouter et gérer un rappel d'appui sur une carte pour un composable 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}")
      }
    }
  )
}