Places UI Kit bileşenine analiz ekleme

Kullanıcıların Yol Tarifi, Telefon veya Web Sitesi'ne dokunması, Google Haritalar'ı açması, yıldız puanına veya yazar atfına dokunması, fotoğraf lightbox'ını açması ya da sekmeler arasında geçiş yapmasıyla ilgili analiz etkinliklerine abone olabilirsiniz. Her etkinlikte, hangi bileşenin ve içerik türünün tetiklendiği, yer kimliği ve konum belirtilir.

Sağlanan Analytics etkinlikleri

Aşağıdaki tabloda, Places UI Kit tarafından sağlanan analiz etkinliklerine dair örnekler verilmiştir.

Kullanıcı arayüzü etkileşimi tags: Set<String> İlişkili içerik/İçerik türü
Yol tarifi düğmesi {"click", "directions", "outbound"} "main_action_button" veya "corner_action_button"
Haritalar'da aç düğmesi {"click", "maps", "outbound"} "main_action_button" veya "corner_action_button"
Ara düğmesi/Telefon numarası (Genel bakış sekmesi) {"click", "call_place", "outbound"} "phone_number", "main_action_button" veya "corner_action_button"
Web sitesi düğmesi/Web sitesi (Genel bakış sekmesi) {"click", "place_website", "outbound"} "website", "main_action_button" veya "corner_action_button"
İlişkilendirme bağlantısı {"click", "attribution", "outbound"} "review" veya "media"
Derecelendirme bağlantısı {"click", "reviews", "outbound"} "rating" veya "review_summaries"
Yasal açıklama bağlantısı (ⓘ iletişim kutusu bağlantıları) {"click", "disclosure", "outbound"} null (yapılandırılamaz)
Rapor bağlantısı {"click", "report", "outbound"} "media", "review" veya "generative_summary"
Yorum bağlantısı {"click", "review", "outbound"} "review"
Medya/fotoğraf bağlantısı {"click", "media", "outbound"} "media"
Fotoğraf Lightbox'ı açıldı (uygulama içi) {"click", "media"} "media"
Genel Bakış sekmesi seçildi (uygulama içi) {"click", "overview_tab"} null
Yorumlar sekmesi seçildi (uygulama içi) {"click", "reviews_tab"} "review"
"Hakkında" sekmesi seçildi (uygulama içi) {"click", "about_tab"} "features"
Yorumlar taşma menüsü (⋮) açıldı (uygulama içi) {"click", "reviews_menu"} "review"
Lightbox taşma menüsü (⋮) açıldı (uygulama içi) {"click", "lightbox_menu"} "media"
Üretken özet menüsü (⋮) açıldı (uygulama içi) {"click", "generative_summary_menu"} "generative_summary"
Üretken yorum özeti menüsü (⋮) açıldı (uygulama içi) {"click", "review_summary_menu"} "review"

Zaman içinde yeni etkinlikler ve etiketler eklenebileceğinden, geliştirme sırasında bir bileşenle etkileşim kurarken yayınlanan her etkinliği günlüğe kaydetmek için genel bir işleyici ekleyebilirsiniz:

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

Analiz etkinliklerine abone olma ve bunları işleme

onPlaceAnalyticsEvent değiştiricisini kullanarak bir kullanıcı arayüzü kiti bileşeninden analiz etkinliklerine abone olabilirsiniz. Değiştiriciyi bir kapsayıcı görünümüne veya doğrudan bir kullanıcı arayüzü kiti bileşenine ekleyebilirsiniz.

Aşağıdaki kod, bir kapsayıcı görünümünde analiz etkinliklerine nasıl abone olunacağını ve bu etkinliklerin nasıl işleneceğini gösterir:

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

Uygulamanız aynı widget türünde birden fazla kart gösteriyorsa (örneğin, iki PlaceDetailsCompactView örneği) .onPlaceAnalyticsEvent öğesini doğrudan her görünüme eklemek, etkinliği hangi kart örneğinin tetiklediğini öğrenmenizi sağlar.

Aşağıdaki kod snippet'inde, doğrudan bir AdvancedPlaceDetailsCompactView bileşeninde analiz etkinliklerine nasıl abone olunacağı ve bu etkinliklerin nasıl işleneceği gösterilmektedir:

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

Kart dokunma geri çağırmalarını ekleme ve işleme

Kart dokunma geri çağırmaları, her kullanıcı arayüzü kiti bileşeni için ayrı ayrı yapılandırılmalı ve işlenmelidir.

Kart gövdesine dokunma işlemlerini işlemek için UI Kit bileşeninde .onTap değiştiricisini kullanın. Kullanıcı karta dokunduğunda .onTap, üç özellik içeren bir Place yapısı iletir:

  • place.placeID (String?): Örneğin, tam bir PlaceDetailsView sayfasını açmak veya bir işaretçi seçmek için kullanılan benzersiz yer kimliği.
  • place.location (CLLocationCoordinate2D): Örneğin, bir harita kamerasını ortalamak veya işaretçi yerleştirmek için yerin enlem/boylam koordinatları.
  • place.viewportInfo (RectangularCoordinateRegion?): Yeri haritada çerçevelemek için önerilen harita görüntü alanı sınırları (northEast ve southWest koordinatları).

Aşağıdaki kodda, AdvancedPlaceDetailsCompactView için kart dokunma geri çağırma işlevinin nasıl ekleneceği ve işleneceği gösterilmektedir:

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