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