在 Places UI Kit 元件中加入數據分析
您可以訂閱分析事件,瞭解使用者是否輕觸「路線」、「通話」或「網站」、開啟 Google 地圖、輕觸星級評等或作者資訊、開啟相片燈箱,或切換分頁。每個事件都會說明觸發的元件和內容類型,以及地點 ID 和位置。
提供的 Analytics 事件
下表列出 Places UI Kit 提供的數據分析事件範例。
| UI 互動 | 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 修飾符,訂閱 UI Kit 元件的數據分析事件。您可以將修飾符附加至容器檢視畫面,或直接附加至 UI Kit 元件。
以下程式碼說明如何在容器檢視中訂閱及處理數據分析事件:
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 ]) } } }
如果應用程式顯示多個相同小工具類型的資訊卡 (例如兩個 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 元件分別設定及處理卡片輕觸回呼。
在 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)") } } } }