Menambahkan analisis ke komponen Places UI Kit

Anda dapat berlangganan peristiwa analisis tentang pengguna yang mengetuk Rute, Telepon, atau Situs, membuka Google Maps, mengetuk rating bintang atau atribusi penulis, membuka lightbox foto, atau beralih tab. Setiap peristiwa menunjukkan komponen dan jenis konten yang diaktifkan, serta ID tempat dan lokasi.

Peristiwa Analytics yang disediakan

Tabel berikut memberikan contoh peristiwa analisis yang disediakan oleh Kit UI Places.

Interaksi UI tags: Set<String> Konten terkait/Jenis konten
Tombol rute {"click", "directions", "outbound"} "main_action_button" atau "corner_action_button"
Tombol Buka di Maps {"click", "maps", "outbound"} "main_action_button" atau "corner_action_button"
Tombol telepon/Nomor telepon (tab Ringkasan) {"click", "call_place", "outbound"} "phone_number", "main_action_button", atau "corner_action_button"
Tombol situs/Situs (tab Ringkasan) {"click", "place_website", "outbound"} "website", "main_action_button", atau "corner_action_button"
Link atribusi {"click", "attribution", "outbound"} "review" atau "media"
Link rating {"click", "reviews", "outbound"} "rating" atau "review_summaries"
Link pengungkapan informasi berdasarkan hukum (link dialog ⓘ) {"click", "disclosure", "outbound"} null (tidak dapat dikonfigurasi)
Laporkan link {"click", "report", "outbound"} "media", "review", atau "generative_summary"
Link ulasan {"click", "review", "outbound"} "review"
Link Media/Foto {"click", "media", "outbound"} "media"
Lightbox Foto dibuka (dalam aplikasi) {"click", "media"} "media"
Tab Ringkasan dipilih (dalam aplikasi) {"click", "overview_tab"} null
Tab ulasan dipilih (dalam aplikasi) {"click", "reviews_tab"} "review"
Tab Tentang dipilih (dalam aplikasi) {"click", "about_tab"} "features"
Menu tambahan ulasan (⋮) dibuka (dalam aplikasi) {"click", "reviews_menu"} "review"
Menu tambahan lightbox (⋮) dibuka (dalam aplikasi) {"click", "lightbox_menu"} "media"
Menu ringkasan generatif (⋮) dibuka (dalam aplikasi) {"click", "generative_summary_menu"} "generative_summary"
Menu ringkasan ulasan generatif (⋮) dibuka (dalam aplikasi) {"click", "review_summary_menu"} "review"

Karena peristiwa dan tag baru dapat ditambahkan seiring waktu, Anda dapat melampirkan pengendali generik selama pengembangan untuk mencatat setiap peristiwa yang disiarkan saat Anda berinteraksi dengan komponen:

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

Berlangganan dan menangani peristiwa analisis

Anda dapat berlangganan peristiwa analisis dari komponen Compose UI Kit dengan menggabungkan penampung tata letak induk atau komponen itu sendiri di ProvidePlacesAnalyticsHandler.

Kode berikut menunjukkan cara berlangganan dan menangani peristiwa analisis dalam hierarki penampung:

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

Jika aplikasi Anda menampilkan beberapa kartu dengan jenis widget yang sama (misalnya, dua composable AdvancedPlaceDetailsCompact), menggabungkan setiap composable dalam ProvidePlacesAnalyticsHandler-nya sendiri akan memberi tahu Anda instance kartu spesifik mana yang memicu peristiwa.

Cuplikan kode berikut menunjukkan cara berlangganan dan menangani peristiwa analisis untuk satu 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"}")
      }
    )
  }
}

Menambahkan dan menangani callback ketukan kartu

Callback ketukan kartu harus dikonfigurasi dan ditangani secara terpisah untuk setiap komponen UI Kit.

Gunakan parameter onClick pada composable UI Kit untuk menangani ketukan pada isi kartu. Saat pengguna mengetuk kartu, onClick akan meneruskan objek Place yang diisi dengan tiga properti:

  • place.id (String?): ID Tempat unik untuk, misalnya, membuka tampilan Place Details lengkap atau memilih penanda.
  • place.location (LatLng?): Koordinat lintang/bujur tempat untuk, misalnya, memusatkan kamera peta atau menempatkan penanda.
  • place.viewport (LatLngBounds?): Batas area pandang peta yang direkomendasikan (koordinat northeast dan southwest) untuk membingkai tempat di peta.

Kode berikut menunjukkan cara menambahkan dan menangani callback ketukan kartu untuk 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}")
      }
    }
  )
}