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