Places UI Kit bileşenine analiz ekleme

Kullanıcıların Yol Tarifi, Telefon veya Web Sitesi'ne dokunması, Google Haritalar'ı açması, yıldız puanına veya yazar atfına dokunması, fotoğraf lightbox'ını açması ya da sekmeler arasında geçiş yapmasıyla ilgili analiz etkinliklerine abone olabilirsiniz. Her etkinlikte, hangi bileşenin ve içerik türünün tetiklendiği, yer kimliği ve konum belirtilir.

Sağlanan Analytics etkinlikleri

Aşağıdaki tabloda, Places UI Kit tarafından sağlanan analiz etkinliklerine dair örnekler verilmiştir.

Kullanıcı arayüzü etkileşimi tags: Set<String> İlişkili içerik/İçerik türü
Yol tarifi düğmesi {"click", "directions", "outbound"} "main_action_button" veya "corner_action_button"
Haritalar'da aç düğmesi {"click", "maps", "outbound"} "main_action_button" veya "corner_action_button"
Ara düğmesi/Telefon numarası (Genel bakış sekmesi) {"click", "call_place", "outbound"} "phone_number", "main_action_button" veya "corner_action_button"
Web sitesi düğmesi/Web sitesi (Genel bakış sekmesi) {"click", "place_website", "outbound"} "website", "main_action_button" veya "corner_action_button"
İlişkilendirme bağlantısı {"click", "attribution", "outbound"} "review" veya "media"
Derecelendirme bağlantısı {"click", "reviews", "outbound"} "rating" veya "review_summaries"
Yasal açıklama bağlantısı (ⓘ iletişim kutusu bağlantıları) {"click", "disclosure", "outbound"} null (yapılandırılamaz)
Rapor bağlantısı {"click", "report", "outbound"} "media", "review" veya "generative_summary"
Yorum bağlantısı {"click", "review", "outbound"} "review"
Medya/fotoğraf bağlantısı {"click", "media", "outbound"} "media"
Fotoğraf Lightbox'ı açıldı (uygulama içi) {"click", "media"} "media"
Genel Bakış sekmesi seçildi (uygulama içi) {"click", "overview_tab"} null
Yorumlar sekmesi seçildi (uygulama içi) {"click", "reviews_tab"} "review"
"Hakkında" sekmesi seçildi (uygulama içi) {"click", "about_tab"} "features"
Yorumlar taşma menüsü (⋮) açıldı (uygulama içi) {"click", "reviews_menu"} "review"
Lightbox taşma menüsü (⋮) açıldı (uygulama içi) {"click", "lightbox_menu"} "media"
Üretken özet menüsü (⋮) açıldı (uygulama içi) {"click", "generative_summary_menu"} "generative_summary"
Üretken yorum özeti menüsü (⋮) açıldı (uygulama içi) {"click", "review_summary_menu"} "review"

Zaman içinde yeni etkinlikler ve etiketler eklenebileceğinden, geliştirme sırasında bir bileşenle etkileşim kurarken yayınlanan her etkinliği günlüğe kaydetmek için genel bir işleyici ekleyebilirsiniz:

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

Analiz etkinliklerine abone olma ve bunları işleme

Bir üst yerleşim kapsayıcısını veya bileşenin kendisini ProvidePlacesAnalyticsHandler içine sarmalayarak bir UI Kit Compose bileşeninden analiz etkinliklerine abone olabilirsiniz.

Aşağıdaki kod, bir kapsayıcı hiyerarşisi içindeki analiz etkinliklerine nasıl abone olunacağını ve bu etkinliklerin nasıl işleneceğini gösterir:

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

Uygulamanız aynı widget türünde birden fazla kart gösteriyorsa (örneğin, iki AdvancedPlaceDetailsCompact composable) her composable'ı kendi ProvidePlacesAnalyticsHandler öğesine sarmalayarak etkinliği hangi kart örneğinin tetiklediğini öğrenebilirsiniz.

Aşağıdaki kod snippet'inde, tek bir AdvancedPlaceDetailsCompact composable için analiz etkinliklerine nasıl abone olunacağı ve bu etkinliklerin nasıl işleneceği gösterilmektedir:

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

Kart dokunma geri çağırmalarını ekleme ve işleme

Kart dokunma geri çağırmaları, her kullanıcı arayüzü kiti bileşeni için ayrı ayrı yapılandırılmalı ve işlenmelidir.

Kart gövdesine dokunma işlemlerini işlemek için kullanıcı arayüzü kiti composable'ında onClick parametresini kullanın. Kullanıcı karta dokunduğunda onClick, üç mülkle doldurulmuş bir Place nesnesi iletir:

  • place.id (String?): Örneğin, tam Yer Ayrıntıları görünümünü açmak veya bir işaretçi seçmek için kullanılan benzersiz yer kimliği.
  • place.location (LatLng?): Örneğin, bir harita kamerasını ortalamak veya işaretçi yerleştirmek için yerin enlem/boylam koordinatları.
  • place.viewport (LatLngBounds?): Yeri haritada çerçevelemek için önerilen harita görüntü alanı sınırları (northeast ve southwest koordinatları).

Aşağıdaki kodda, AdvancedPlaceDetailsCompact composable'ı için kart dokunma geri çağırma işlevinin nasıl ekleneceği ve işleneceği gösterilmektedir:

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