向 Places UI Kit 组件添加分析功能

您可以订阅与以下用户操作相关的分析事件:点按“路线”“致电”或“网站”,打开 Google 地图,点按星级或作者署名,打开照片灯箱,或切换标签页。每个事件都会说明触发的组件和内容类型,以及地点 ID 和位置。

提供的 Analytics 事件

下表提供了 Places UI Kit 提供的分析事件示例。

界面互动 tags: Set<String> 关联的内容/内容类型
“路线”按钮 {"click", "directions", "outbound"} "main_action_button" 或 "corner_action_button"
“在 Google 地图中打开”按钮 {"click", "maps", "outbound"} "main_action_button" 或 "corner_action_button"
“致电”按钮/电话号码(“概览”标签页) {"click", "call_place", "outbound"} "phone_number"、"main_action_button" 或 "corner_action_button"
“网站”按钮/“网站”(“概览”标签页) {"click", "place_website", "outbound"} "website"、"main_action_button" 或 "corner_action_button"
归因链接 {"click", "attribution", "outbound"} "review" 或 "media"
评分链接 {"click", "reviews", "outbound"} "rating" 或 "review_summaries"
依法披露链接(ⓘ 个对话框链接) {"click", "disclosure", "outbound"} null(不可配置)
报告链接 {"click", "report", "outbound"} "media"、"review" 或 "generative_summary"
评价链接 {"click", "review", "outbound"} "review"
媒体/照片链接 {"click", "media", "outbound"} "media"
照片灯箱已打开(应用内) {"click", "media"} "media"
已选择“概览”标签页(应用内) {"click", "overview_tab"} null
已选择“评价”标签页(应用内) {"click", "reviews_tab"} "review"
已选择“关于”标签页(应用内) {"click", "about_tab"} "features"
已打开评价溢出菜单 (⋮)(应用内) {"click", "reviews_menu"} "review"
灯箱溢出菜单 (⋮) 已打开(应用内) {"click", "lightbox_menu"} "media"
已打开生成式摘要菜单 (⋮)(应用内) {"click", "generative_summary_menu"} "generative_summary"
生成式评价摘要菜单 (⋮) 已打开(应用内) {"click", "review_summary_menu"} "review"

由于新事件和标记可能会随着时间的推移而添加,因此您可以在开发期间附加通用处理程序,以记录您与组件互动时广播的每个事件:

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

订阅和处理分析事件

您可以通过将父布局容器或组件本身封装在 ProvidePlacesAnalyticsHandler 中,订阅来自界面套件 Compose 组件的分析事件。

以下代码展示了如何在容器层次结构中订阅和处理分析事件:

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

如果您的应用显示同一 widget 类型的多个卡片(例如,两个 AdvancedPlaceDetailsCompact 可组合项),将每个可组合项封装在各自的 ProvidePlacesAnalyticsHandler 中,您就可以知道是哪个特定卡片实例触发了事件。

以下代码段展示了如何为单个 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"}")
      }
    )
  }
}

添加和处理卡片点按回调

必须为每个界面套件组件单独配置和处理卡片点按回调。

在界面套件可组合项上使用 onClick 参数,以处理对卡片正文的点按操作。当用户点按卡片时,onClick 会传递一个 Place 对象,其中填充了三个属性:

  • place.id (String?):唯一的地点 ID,例如,用于打开完整的地点详情视图或选择标记。
  • place.location (LatLng?):地点的纬度/经度坐标,例如,用于将地图镜头居中或放置标记。
  • place.viewport (LatLngBounds?):建议的地图视口边界(northeast 和 southwest 坐标),用于在地图上框定地点。

以下代码展示了如何为 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}")
      }
    }
  )
}