Add analytics to a Places UI Kit component

You can subscribe to analytics events about users tapping Directions, Call or Website, opening Google Maps, tapping the star rating or an author attribution, opening the photo lightbox, or switching tabs. Each event says which component and content type fired, as well as the place ID and location.

Analytics events that are provided

The following table provides examples of analytics events that are provided by the Places UI Kit.

UI Interaction tags: Set<String> Associated content/Content type
Directions button {"click", "directions", "outbound"} "main_action_button" or "corner_action_button"
Open in Maps button {"click", "maps", "outbound"} "main_action_button" or "corner_action_button"
Call button / Phone number (Overview tab) {"click", "call_place", "outbound"} "phone_number", "main_action_button", or "corner_action_button"
Website button / Website (Overview tab) {"click", "place_website", "outbound"} "website", "main_action_button", or "corner_action_button"
Attribution link {"click", "attribution", "outbound"} "review" or "media"
Rating link {"click", "reviews", "outbound"} "rating" or "review_summaries"
Legal disclosure link (ⓘ dialog links) {"click", "disclosure", "outbound"} null (not configurable)
Report link {"click", "report", "outbound"} "media", "review", or "generative_summary"
Review link {"click", "review", "outbound"} "review"
Media / Photo link {"click", "media", "outbound"} "media"
Photo Lightbox opened (in-app) {"click", "media"} "media"
Overview tab selected (in-app) {"click", "overview_tab"} null
Reviews tab selected (in-app) {"click", "reviews_tab"} "review"
About tab selected (in-app) {"click", "about_tab"} "features"
Reviews overflow menu (⋮) opened (in-app) {"click", "reviews_menu"} "review"
Lightbox overflow menu (⋮) opened (in-app) {"click", "lightbox_menu"} "media"
Generative summary menu (⋮) opened (in-app) {"click", "generative_summary_menu"} "generative_summary"
Generative review summary menu (⋮) opened (in-app) {"click", "review_summary_menu"} "review"

Because new events and tags may be added over time, you can attach a generic handler during development to log every event that is broadcast as you interact with a component:

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

Subscribe to and handle analytics events

You can subscribe to analytics events from a UI Kit component by using the onPlaceAnalyticsEvent modifier. You can attach the modifier to a container view or directly to a UI Kit component.

The following code shows how to subscribe to and handle analytics events within a container view:

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
      ])
    }
  }
}

If your app displays multiple cards of the same widget type (for instance, two PlaceDetailsCompactView instances), attaching .onPlaceAnalyticsEvent directly to each view lets you know which specific card instance triggered the event.

The following code snippet shows how to subscribe to and handle analytics events directly on an AdvancedPlaceDetailsCompactView component:

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

Add and handle card tap callbacks

Card tap callbacks must be configured and handled separately for each UI Kit component.

Use the .onTap modifier on a UI Kit component to handle taps on the card body. When the user taps the card, .onTap passes a Place struct populated with three properties:

  • place.placeID (String?): The unique Place ID to, for example, open a full PlaceDetailsView sheet or select a marker.
  • place.location (CLLocationCoordinate2D): The latitude/longitude coordinates of the place to, for example, center a map camera or place a marker.
  • place.viewportInfo (RectangularCoordinateRegion?): The recommended map viewport bounds (northEast and southWest coordinates) for framing the place on a map.

The following code shows how to add and handle a card tap callback for an 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)")
      }
    }
  }
}