Menambahkan analisis ke komponen Places UI Kit

Anda dapat berlangganan peristiwa analisis tentang pengguna yang mengetuk Rute, Telepon, atau Situs, membuka Google Maps, mengetuk rating bintang atau atribusi penulis, membuka lightbox foto, atau beralih tab. Setiap peristiwa menunjukkan komponen dan jenis konten yang diaktifkan, serta ID tempat dan lokasi.

Peristiwa Analytics yang disediakan

Tabel berikut memberikan contoh peristiwa analisis yang disediakan oleh Kit UI Places.

Interaksi UI tags: Set<String> Konten terkait/Jenis konten
Tombol rute {"click", "directions", "outbound"} "main_action_button" atau "corner_action_button"
Tombol Buka di Maps {"click", "maps", "outbound"} "main_action_button" atau "corner_action_button"
Tombol telepon/Nomor telepon (tab Ringkasan) {"click", "call_place", "outbound"} "phone_number", "main_action_button", atau "corner_action_button"
Tombol situs/Situs (tab Ringkasan) {"click", "place_website", "outbound"} "website", "main_action_button", atau "corner_action_button"
Link atribusi {"click", "attribution", "outbound"} "review" atau "media"
Link rating {"click", "reviews", "outbound"} "rating" atau "review_summaries"
Link pengungkapan informasi berdasarkan hukum (link dialog ⓘ) {"click", "disclosure", "outbound"} null (tidak dapat dikonfigurasi)
Laporkan link {"click", "report", "outbound"} "media", "review", atau "generative_summary"
Link ulasan {"click", "review", "outbound"} "review"
Link Media/Foto {"click", "media", "outbound"} "media"
Lightbox Foto dibuka (dalam aplikasi) {"click", "media"} "media"
Tab Ringkasan dipilih (dalam aplikasi) {"click", "overview_tab"} null
Tab ulasan dipilih (dalam aplikasi) {"click", "reviews_tab"} "review"
Tab Tentang dipilih (dalam aplikasi) {"click", "about_tab"} "features"
Menu tambahan ulasan (⋮) dibuka (dalam aplikasi) {"click", "reviews_menu"} "review"
Menu tambahan lightbox (⋮) dibuka (dalam aplikasi) {"click", "lightbox_menu"} "media"
Menu ringkasan generatif (⋮) dibuka (dalam aplikasi) {"click", "generative_summary_menu"} "generative_summary"
Menu ringkasan ulasan generatif (⋮) dibuka (dalam aplikasi) {"click", "review_summary_menu"} "review"

Karena peristiwa dan tag baru dapat ditambahkan seiring waktu, Anda dapat melampirkan pengendali generik selama pengembangan untuk mencatat setiap peristiwa yang disiarkan saat Anda berinteraksi dengan komponen:

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

Berlangganan dan menangani peristiwa analisis

Anda dapat berlangganan peristiwa analisis dari komponen UI Kit menggunakan pengubah onPlaceAnalyticsEvent. Anda dapat melampirkan pengubah ke tampilan penampung atau langsung ke komponen UI Kit.

Kode berikut menunjukkan cara berlangganan dan menangani peristiwa analisis dalam tampilan penampung:

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

Jika aplikasi Anda menampilkan beberapa kartu dengan jenis widget yang sama (misalnya, dua instance PlaceDetailsCompactView), melampirkan .onPlaceAnalyticsEvent langsung ke setiap tampilan akan memungkinkan Anda mengetahui instance kartu spesifik mana yang memicu peristiwa.

Cuplikan kode berikut menunjukkan cara berlangganan dan menangani peristiwa analisis langsung di komponen 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")
        }
      }
  }
}

Menambahkan dan menangani callback ketukan kartu

Callback ketukan kartu harus dikonfigurasi dan ditangani secara terpisah untuk setiap komponen UI Kit.

Gunakan pengubah .onTap pada komponen UI Kit untuk menangani ketukan pada isi kartu. Saat pengguna mengetuk kartu, .onTap akan meneruskan struct Place yang diisi dengan tiga properti:

  • place.placeID (String?): ID Tempat unik untuk, misalnya, membuka sheet PlaceDetailsView lengkap atau memilih penanda.
  • place.location (CLLocationCoordinate2D): Koordinat lintang/bujur tempat untuk, misalnya, memusatkan kamera peta atau menempatkan penanda.
  • place.viewportInfo (RectangularCoordinateRegion?): Batas area pandang peta yang direkomendasikan (koordinat northEast dan southWest) untuk membingkai tempat di peta.

Kode berikut menunjukkan cara menambahkan dan menangani callback ketukan kartu untuk 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)")
      }
    }
  }
}