在 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" |
由於系統可能會隨著時間新增事件和標記,因此您可以在開發期間附加一般處理常式,記錄與元件互動時播送的每個事件:
// 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 中,訂閱 UI Kit 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"}") } ) } } }
如果應用程式顯示多張相同小工具類型的資訊卡 (例如兩個 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"}") } ) } }
新增及處理卡片輕觸回呼
您必須為每個 UI Kit 元件分別設定及處理卡片輕觸回呼。
在 UI Kit 可組合函式上使用 onClick 參數,處理卡片主體的輕觸動作。使用者輕觸卡片時,onClick 會傳遞 Place 物件,其中填入三個屬性:
place.id(String?):專屬地點 ID,例如用於開啟完整的 Place Details 檢視畫面或選取標記。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}") } } ) }