向 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" |
由于新事件和标记可能会随着时间的推移而添加,因此您可以在开发期间附加通用处理程序,以记录您与组件互动时广播的每个事件:
// Attach to a Places UI Kit view or a parent container to inspect all broadcast events .onPlaceAnalyticsEvent { event in print( "Analytics event — component: \(event.componentType), " + "tags: \(event.tags.sorted()), " + "content: \(event.contentType ?? "nil"), " + "places: \(event.places.compactMap(\.placeID))" ) }
订阅和处理分析事件
您可以使用 onPlaceAnalyticsEvent 修饰符订阅界面套件组件中的分析事件。您可以将修饰符附加到容器视图或直接附加到界面套件组件。
以下代码展示了如何在容器视图中订阅和处理分析事件:
import SwiftUI import PlacesSwift struct PlaceCardScreen: View { @State private var query = PlaceDetailsQuery(identifier: .placeID("ChIJN1t_tDeuEmsRUsoyG83frY4")) var configuration: PlaceDetailsCompactConfiguration { return PlaceDetailsCompactConfiguration( content: PlaceDetailsCompactView.standardContent, theme: PlacesMaterialTheme() ) } var body: some View { VStack { PlaceDetailsCompactView(query: $query, configuration: configuration, placeDetailsCallback: { _ in }) // 1. Direct card tap (for UI navigation, e.g., centering a map) .onTap { place in print("Card tapped for place ID: \(place.placeID ?? "unknown")") } } // 2. Analytics callback (can be attached to the card or any parent container) .onPlaceAnalyticsEvent { event in let placeID = event.places.first?.placeID ?? "none" // Option A: Check for specific interactions using built-in Tag constants if event.tags.contains(PlaceAnalyticsEvent.Tag.directions) { print("User requested directions for place: \(placeID)") } if event.tags.contains(PlaceAnalyticsEvent.Tag.outbound) { print("User is leaving the app via: \(event.tags.sorted().joined(separator: ", "))") } // Option B: Forward every event directly to your analytics SDK (e.g., Firebase) Analytics.logEvent("place_ui_kit_interaction", parameters: [ "component_type": event.componentType, "content_type": event.contentType ?? "none", "tags": event.tags.sorted().joined(separator: ","), "place_id": placeID ]) } } }
如果您的应用显示同一 widget 类型的多个卡片(例如,两个 PlaceDetailsCompactView 实例),则直接将 .onPlaceAnalyticsEvent 附加到每个视图可让您知道是哪个特定卡片实例触发了事件。
以下代码段展示了如何直接在 AdvancedPlaceDetailsCompactView 组件上订阅和处理分析事件:
import SwiftUI import PlacesSwift struct SinglePlaceCardView: View { @State private var query = PlaceDetailsQuery( identifier: .placeID("ChIJN1t_tDeuEmsRUsoyG83frY4") ) private var configuration: AdvancedPlaceDetailsCompactConfiguration { AdvancedPlaceDetailsCompactConfiguration( content: AdvancedPlaceDetailsCompactView.standardContent, theme: PlacesMaterialTheme() ) } var body: some View { AdvancedPlaceDetailsCompactView( orientation: .horizontal, query: $query, configuration: configuration ) { _ in } // 1. Direct card-tap callback (must come before generic `View` modifiers) .onTap { place in print("Tapped card for place: \(place.placeID ?? "unknown")") } // 2. Analytics callback scoped to this specific view instance .onPlaceAnalyticsEvent { event in let placeIDs = event.places.compactMap(\.placeID).joined(separator: ", ") let tags = event.tags.sorted().joined(separator: ", ") print("[\(tags)] in \(event.componentType), content: \(event.contentType ?? "nil"), places: [\(placeIDs)]") if event.tags.contains(PlaceAnalyticsEvent.Tag.directions) { print("Directions tapped on this card") } } } }
添加和处理卡片点按回调
必须为每个界面套件组件单独配置和处理卡片点按回调。
在 UI Kit 组件上使用 .onTap 修饰符,以处理对卡片主体的点按操作。当用户点按卡片时,.onTap 会传递一个 Place 结构体,其中填充了三个属性:
place.placeID(String?):唯一的地点 ID,例如,用于打开完整的PlaceDetailsView表格或选择标记。place.location(CLLocationCoordinate2D):地点的纬度/经度坐标,例如,用于将地图镜头居中或放置标记。place.viewportInfo(RectangularCoordinateRegion?):建议的地图视口边界(northEast和southWest坐标),用于在地图上框定地点。
以下代码展示了如何为 AdvancedPlaceDetailsCompactView 添加和处理卡片点按回调:
import CoreLocation import PlacesSwift import SwiftUI struct PlaceCardTapSampleView: View { static let peetsCoffeePlaceID = "ChIJT7FdmYiAhYAROFOvrIxRJDU" @State private var query = PlaceDetailsQuery( identifier: .placeID(peetsCoffeePlaceID) ) @State private var selectedPlace: Place? var body: some View { AdvancedPlaceDetailsCompactView( orientation: .horizontal, query: $query, configuration: AdvancedPlaceDetailsCompactConfiguration( content: AdvancedPlaceDetailsCompactView.standardContent, theme: PlacesMaterialTheme() ), placeDetailsCallback: { _ in } ) .onTap { place in // Handle the card tap using place.placeID, place.location, or place.viewportInfo selectedPlace = place print("Tapped place ID: \(place.placeID ?? "unknown")") print("Coordinates: \(place.location.latitude), \(place.location.longitude)") if let viewport = place.viewportInfo { print("Viewport NE: \(viewport.northEast), SW: \(viewport.southWest)") } } } }