Analysen zu einer Places UI Kit-Komponente hinzufügen

Sie können Analyseereignisse abonnieren, die ausgelöst werden, wenn Nutzer auf „Route“, „Anrufen“ oder „Website“ tippen, Google Maps öffnen, auf die Sternebewertung oder eine Urheberangabe tippen, die Fotogalerie öffnen oder Tabs wechseln. Für jedes Ereignis wird angegeben, welche Komponente und welcher Inhaltstyp ausgelöst wurden, sowie die Orts-ID und der Standort.

Bereitgestellte Analytics-Ereignisse

In der folgenden Tabelle finden Sie Beispiele für Analyseereignisse, die vom Places UI Kit bereitgestellt werden.

UI-Interaktion tags: Set<String> Verknüpfter Inhalt/Inhaltstyp
Button „Route“ {"click", "directions", "outbound"} "main_action_button" oder "corner_action_button"
Schaltfläche „In Maps öffnen“ {"click", "maps", "outbound"} "main_action_button" oder "corner_action_button"
Schaltfläche „Anruf“ / Telefonnummer (Tab „Übersicht“) {"click", "call_place", "outbound"} "phone_number", "main_action_button" oder "corner_action_button"
Schaltfläche „Website“ / Website (Tab „Übersicht“) {"click", "place_website", "outbound"} "website", "main_action_button" oder "corner_action_button"
Attribution link {"click", "attribution", "outbound"} "review" oder "media"
Link zur Bewertung {"click", "reviews", "outbound"} "rating" oder "review_summaries"
Link zur rechtlichen Offenlegung (ⓘ Dialogfeldlinks) {"click", "disclosure", "outbound"} null (nicht konfigurierbar)
Link zum Bericht {"click", "report", "outbound"} "media", "review" oder "generative_summary"
Review link {"click", "review", "outbound"} "review"
Medien-/Fotolink {"click", "media", "outbound"} "media"
Foto-Lightbox geöffnet (In-App) {"click", "media"} "media"
Tab „Übersicht“ ausgewählt (In-App) {"click", "overview_tab"} null
Tab „Rezensionen“ ausgewählt (In-App) {"click", "reviews_tab"} "review"
Tab „Über“ ausgewählt (In-App) {"click", "about_tab"} "features"
Dreipunkt-Menü für Rezensionen (⋮) geöffnet (In-App) {"click", "reviews_menu"} "review"
Dreipunkt-Menü der Lightbox (⋮) geöffnet (In-App) {"click", "lightbox_menu"} "media"
Menü für generative Zusammenfassung (⋮) geöffnet (in der App) {"click", "generative_summary_menu"} "generative_summary"
Menü für generativen Rezensionsüberblick (⋮) geöffnet (In-App) {"click", "review_summary_menu"} "review"

Da im Laufe der Zeit neue Ereignisse und Tags hinzugefügt werden können, können Sie während der Entwicklung einen generischen Handler anhängen, um jedes Ereignis zu protokollieren, das bei der Interaktion mit einer Komponente übertragen wird:

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

Analyseereignisse abonnieren und verarbeiten

Sie können Analyseereignisse von einer UI Kit-Komponente abonnieren, indem Sie den Modifikator onPlaceAnalyticsEvent verwenden. Sie können den Modifikator an eine Containeransicht oder direkt an eine UI Kit-Komponente anhängen.

Der folgende Code zeigt, wie Sie Analyseereignisse in einer Containeransicht abonnieren und verarbeiten:

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

Wenn in Ihrer App mehrere Karten desselben Widget-Typs angezeigt werden (z. B. zwei PlaceDetailsCompactView-Instanzen), können Sie durch direktes Anhängen von .onPlaceAnalyticsEvent an jede Ansicht feststellen, welche spezifische Karteninstanz das Ereignis ausgelöst hat.

Das folgende Code-Snippet zeigt, wie Sie Analyseereignisse direkt in einer AdvancedPlaceDetailsCompactView-Komponente abonnieren und verarbeiten:

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

Callbacks für das Tippen auf Karten hinzufügen und verarbeiten

Callbacks für das Tippen auf Karten müssen für jede UI-Kit-Komponente separat konfiguriert und verarbeitet werden.

Verwenden Sie den Modifikator .onTap für eine UI-Kit-Komponente, um Tippen auf den Karteninhalt zu verarbeiten. Wenn der Nutzer auf die Karte tippt, übergibt .onTap eine Place-Struktur mit drei Attributen:

  • place.placeID (String?): Die eindeutige Orts-ID, um beispielsweise eine vollständige PlaceDetailsView-Tabelle zu öffnen oder eine Markierung auszuwählen.
  • place.location (CLLocationCoordinate2D): Die Breiten- und Längengradkoordinaten des Ortes, um beispielsweise eine Kartenkamera zu zentrieren oder eine Markierung zu platzieren.
  • place.viewportInfo (RectangularCoordinateRegion?): Die empfohlenen Grenzen des Darstellungsbereichs der Karte (northEast- und southWest-Koordinaten) für die Darstellung des Ortes auf einer Karte.

Der folgende Code zeigt, wie Sie einen Callback für das Tippen auf eine Karte für ein AdvancedPlaceDetailsCompactView hinzufügen und verarbeiten:

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