Thêm số liệu phân tích vào một thành phần của Places UI Kit

Bạn có thể đăng ký nhận sự kiện phân tích về việc người dùng nhấn vào Đường đi, Gọi điện hoặc Trang web, mở Google Maps, nhấn vào điểm xếp hạng theo sao hoặc thông tin ghi nhận tác giả, mở hộp đèn ảnh hoặc chuyển đổi thẻ. Mỗi sự kiện cho biết thành phần và loại nội dung nào đã kích hoạt, cũng như mã địa điểm và vị trí.

Sự kiện Analytics được cung cấp

Bảng sau đây cung cấp ví dụ về các sự kiện phân tích do Places UI Kit cung cấp.

Tương tác với giao diện người dùng tags: Set<String> Nội dung liên quan/Loại nội dung
Nút Đường đi {"click", "directions", "outbound"} "main_action_button" hoặc "corner_action_button"
Nút Mở trong Maps {"click", "maps", "outbound"} "main_action_button" hoặc "corner_action_button"
Nút gọi/Số điện thoại (thẻ Tổng quan) {"click", "call_place", "outbound"} "phone_number", "main_action_button" hoặc "corner_action_button"
Nút trang web/Trang web (thẻ Tổng quan) {"click", "place_website", "outbound"} "website", "main_action_button" hoặc "corner_action_button"
Đường liên kết phân bổ {"click", "attribution", "outbound"} "review" hoặc "media"
Đường liên kết đến điểm xếp hạng {"click", "reviews", "outbound"} "rating" hoặc "review_summaries"
Đường liên kết đến công bố thông tin theo quy định pháp lý (đường liên kết trong hộp thoại ⓘ) {"click", "disclosure", "outbound"} null (không thể định cấu hình)
Đường liên kết đến báo cáo {"click", "report", "outbound"} "media", "review" hoặc "generative_summary"
Đường liên kết xem lại {"click", "review", "outbound"} "review"
Đường liên kết đến nội dung nghe nhìn/ảnh {"click", "media", "outbound"} "media"
Đã mở hộp đèn ảnh (trong ứng dụng) {"click", "media"} "media"
Đã chọn thẻ Tổng quan (trong ứng dụng) {"click", "overview_tab"} null
Đã chọn thẻ Bài đánh giá (trong ứng dụng) {"click", "reviews_tab"} "review"
Đã chọn thẻ Giới thiệu (trong ứng dụng) {"click", "about_tab"} "features"
Đã mở trình đơn mục bổ sung của bài đánh giá (⋮) (trong ứng dụng) {"click", "reviews_menu"} "review"
Đã mở trình đơn mục bổ sung của hộp đèn (⋮) (trong ứng dụng) {"click", "lightbox_menu"} "media"
Đã mở trình đơn tóm tắt bằng AI tạo sinh (⋮) (trong ứng dụng) {"click", "generative_summary_menu"} "generative_summary"
Đã mở trình đơn tóm tắt bài đánh giá bằng AI tạo sinh (⋮) (trong ứng dụng) {"click", "review_summary_menu"} "review"

Vì các sự kiện và thẻ mới có thể được thêm vào theo thời gian, nên bạn có thể đính kèm một trình xử lý chung trong quá trình phát triển để ghi lại mọi sự kiện được truyền phát khi bạn tương tác với một thành phần:

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

Đăng ký và xử lý các sự kiện phân tích

Bạn có thể đăng ký nhận sự kiện phân tích từ một thành phần Compose của Bộ giao diện người dùng bằng cách gói vùng chứa bố cục mẹ hoặc chính thành phần đó trong ProvidePlacesAnalyticsHandler.

Mã sau đây cho biết cách đăng ký và xử lý các sự kiện phân tích trong hệ phân cấp vùng chứa:

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

Nếu ứng dụng của bạn hiển thị nhiều thẻ của cùng một loại tiện ích (ví dụ: hai thành phần kết hợp AdvancedPlaceDetailsCompact), thì việc gói từng thành phần kết hợp trong ProvidePlacesAnalyticsHandler riêng sẽ giúp bạn biết được thực thể thẻ cụ thể nào đã kích hoạt sự kiện.

Đoạn mã sau đây cho biết cách đăng ký và xử lý các sự kiện phân tích cho một 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"}")
      }
    )
  }
}

Thêm và xử lý lệnh gọi lại khi nhấn vào thẻ

Bạn phải định cấu hình và xử lý riêng các lệnh gọi lại khi nhấn vào thẻ cho từng thành phần của Bộ giao diện người dùng.

Sử dụng tham số onClick trên thành phần kết hợp Bộ giao diện người dùng để xử lý các lần nhấn vào phần nội dung của thẻ. Khi người dùng nhấn vào thẻ, onClick sẽ truyền một đối tượng Place được điền sẵn 3 thuộc tính:

  • place.id (String?): Mã địa điểm riêng biệt, chẳng hạn như để mở chế độ xem Chi tiết địa điểm đầy đủ hoặc chọn một điểm đánh dấu.
  • place.location (LatLng?): Toạ độ vĩ độ/kinh độ của địa điểm, ví dụ: để căn giữa camera bản đồ hoặc đặt điểm đánh dấu.
  • place.viewport (LatLngBounds?): Các ranh giới khung nhìn bản đồ được đề xuất (toạ độ northeast và southwest) để định khung địa điểm trên bản đồ.

Đoạn mã sau đây cho biết cách thêm và xử lý lệnh gọi lại khi nhấn vào thẻ cho một thành phần kết hợp 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}")
      }
    }
  )
}