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