Ajouter des analyses à un composant du Kit UI pour Places

Vous pouvez vous abonner aux événements d'analyse concernant les utilisateurs qui appuient sur "Itinéraire", "Appeler" ou "Site Web", ouvrent Google Maps, appuient sur la note ou l'attribution de l'auteur, ouvrent la visionneuse de photos ou changent d'onglet. Chaque événement indique le composant et le type de contenu qui ont été déclenchés, ainsi que l'ID de lieu et l'emplacement.

Événements Analytics fournis

Le tableau suivant fournit des exemples d'événements d'analyse fournis par le Kit UI pour Places.

Interaction avec l'UI tags: Set<String> Contenu associé/Type de contenu
Bouton "Itinéraire" {"click", "directions", "outbound"} "main_action_button" ou "corner_action_button"
Bouton "Ouvrir dans Maps" {"click", "maps", "outbound"} "main_action_button" ou "corner_action_button"
Bouton d'appel/Numéro de téléphone (onglet "Aperçu") {"click", "call_place", "outbound"} "phone_number", "main_action_button" ou "corner_action_button"
Bouton "Site Web"/Site Web (onglet "Aperçu") {"click", "place_website", "outbound"} "website", "main_action_button" ou "corner_action_button"
Lien d'attribution {"click", "attribution", "outbound"} "review" ou "media"
Lien d'évaluation {"click", "reviews", "outbound"} "rating" ou "review_summaries"
Lien vers les mentions légales (liens de la boîte de dialogue ⓘ) {"click", "disclosure", "outbound"} null (non configurable)
Lien vers le rapport {"click", "report", "outbound"} "media", "review" ou "generative_summary"
Lien d'avis {"click", "review", "outbound"} "review"
Lien vers le média/la photo {"click", "media", "outbound"} "media"
Lightbox de photo ouverte (dans l'application) {"click", "media"} "media"
Onglet "Aperçu" sélectionné (dans l'application) {"click", "overview_tab"} null
Onglet "Avis" sélectionné (dans l'application) {"click", "reviews_tab"} "review"
Onglet "À propos" sélectionné (dans l'application) {"click", "about_tab"} "features"
Menu à développer des avis (⋮) ouvert (dans l'application) {"click", "reviews_menu"} "review"
Menu à développer Lightbox (⋮) ouvert (dans l'application) {"click", "lightbox_menu"} "media"
Menu "Résumé génératif" (⋮) ouvert (dans l'application) {"click", "generative_summary_menu"} "generative_summary"
Menu du résumé des avis génératif (⋮) ouvert (dans l'application) {"click", "review_summary_menu"} "review"

Étant donné que de nouveaux événements et tags peuvent être ajoutés au fil du temps, vous pouvez associer un gestionnaire générique pendant le développement pour consigner chaque événement diffusé lorsque vous interagissez avec un composant :

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

S'abonner aux événements d'analyse et les gérer

Vous pouvez vous abonner aux événements d'analyse d'un composant UI Kit à l'aide du modificateur onPlaceAnalyticsEvent. Vous pouvez associer le modificateur à une vue de conteneur ou directement à un composant du kit d'interface utilisateur.

Le code suivant montre comment s'abonner aux événements d'analyse et les gérer dans une vue de conteneur :

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

Si votre application affiche plusieurs fiches du même type de widget (par exemple, deux instances PlaceDetailsCompactView), l'association de .onPlaceAnalyticsEvent directement à chaque vue vous permet de savoir quelle instance de fiche spécifique a déclenché l'événement.

L'extrait de code suivant montre comment s'abonner aux événements d'analyse et les gérer directement sur un composant 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")
        }
      }
  }
}

Ajouter et gérer des rappels d'appui sur une carte

Les rappels de pression sur une carte doivent être configurés et gérés séparément pour chaque composant du kit d'interface utilisateur.

Utilisez le modificateur .onTap sur un composant du kit UI pour gérer les appuis sur le corps de la carte. Lorsque l'utilisateur appuie sur la carte, .onTap transmet une structure Place contenant trois propriétés :

  • place.placeID (String?) : ID de lieu unique permettant, par exemple, d'ouvrir une fiche PlaceDetailsView complète ou de sélectionner un repère.
  • place.location (CLLocationCoordinate2D) : coordonnées de latitude/longitude du lieu, par exemple pour centrer la caméra de la carte ou placer un repère.
  • place.viewportInfo (RectangularCoordinateRegion?) : limites de la fenêtre d'affichage de la carte recommandées (coordonnées northEast et southWest) pour cadrer le lieu sur une carte.

Le code suivant montre comment ajouter et gérer un rappel d'appui sur une carte pour un 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)")
      }
    }
  }
}