افزودن Analytics به مؤلفه «کیت میانای کاربر جاها»

می‌توانید در رویدادهای تجزیه‌وتحلیل مربوط به تک‌ضرب زدن کاربران روی «مسیرها»، «تماس»، یا «وب‌سایت»، باز کردن Google Maps، تک‌ضرب زدن روی رده‌بندی ستاره یا ارجاع به نویسنده، باز کردن لایت‌باکس عکس، یا جابه‌جا شدن بین برگه‌ها مشترک شوید. هر رویداد می‌گوید کدام مؤلفه و نوع محتوا فعال شده است، و همچنین شناسه مکان و موقعیت مکانی را نشان می‌دهد.

رویدادهای Analytics که ارائه شده است

جدول زیر نمونه‌هایی از رویدادهای تجزیه‌وتحلیل را که توسط «کیت میانای کاربر جاها» ارائه می‌شود نشان می‌دهد.

تعامل با میانای کاربر tags: Set<String> محتوای مرتبط/نوع محتوا
دکمه مسیرها {"click", "directions", "outbound"} ‫"main_action_button" یا "corner_action_button"
دکمه «باز کردن در Maps» {"click", "maps", "outbound"} ‫"main_action_button" یا "corner_action_button"
دکمه تماس / شماره تلفن (برگه نمای کلی) {"click", "call_place", "outbound"} ‫"phone_number"، "main_action_button"، یا "corner_action_button"
دکمه وب‌سایت / وب‌سایت (برگه نمای کلی) {"click", "place_website", "outbound"} ‫"website"، "main_action_button"، یا "corner_action_button"
پیوند ارجاع {"click", "attribution", "outbound"} ‫"review" یا "media"
پیوند رده‌بندی {"click", "reviews", "outbound"} ‫"rating" یا "review_summaries"
پیوند شفاف‌سازی قانونی (پیوندهای کادر گفتگوی ⓘ) {"click", "disclosure", "outbound"} ‫null (پیکربندی‌ناپذیر)
گزارش کردن پیوند {"click", "report", "outbound"} ‫"media"، "review"، یا "generative_summary"
پیوند مرور {"click", "review", "outbound"} "review"
پیوند رسانه / عکس {"click", "media", "outbound"} "media"
«میز نور عکس» باز شد (درون‌برنامه) {"click", "media"} "media"
زبانه «نمای کلی» انتخاب شد (درون‌برنامه) {"click", "overview_tab"} null
برگه «مرورها» انتخاب شد (درون‌برنامه) {"click", "reviews_tab"} "review"
برگه «درباره» انتخاب شد (درون‌برنامه) {"click", "about_tab"} "features"
منوِ سرریز مرورها (⋮) باز شد (درون‌برنامه) {"click", "reviews_menu"} "review"
منوِ سرریز Lightbox (⋮) باز شد (درون‌برنامه) {"click", "lightbox_menu"} "media"
منو خلاصه زایا (⋮) باز شد (درون‌برنامه) {"click", "generative_summary_menu"} "generative_summary"
منو خلاصه مرورهای زایا (⋮) باز شد (درون‌برنامه) {"click", "review_summary_menu"} "review"

ازآنجایی‌که ممکن است رویدادها و برچسب‌های جدیدی درطول زمان اضافه شوند، می‌توانید یک کنترل‌کننده عمومی را درطول توسعه پیوست کنید تا هر رویدادی را که هنگام تعامل با یک مؤلفه پخش می‌شود ثبت کنید:

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

مشترک شدن در رویدادهای Analytics و مدیریت آن‌ها

بااستفاده از اصلاح‌کننده onPlaceAnalyticsEvent می‌توانید در رویدادهای تجزیه‌وتحلیل از مؤلفه UI Kit مشترک شوید. می‌توانید اصلاح‌کننده را به نمای محفظه یا مستقیماً به مؤلفه UI Kit پیوست کنید.

کد زیر نحوه مشترک شدن و مدیریت رویدادهای Analytics را در نمای محفظه نشان می‌دهد:

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

اگر برنامه‌تان چند کارت از یک نوع ابزاره را نمایش می‌دهد (برای مثال، دو نمونه PlaceDetailsCompactView)، پیوست کردن مستقیم .onPlaceAnalyticsEvent به هر نما به شما امکان می‌دهد بدانید کدام نمونه کارت خاص رویداد را راه‌اندازی کرده است.

تکه‌کد زیر نشان می‌دهد که چگونه می‌توان مستقیماً در مؤلفه AdvancedPlaceDetailsCompactView در رویدادهای Analytics مشترک شد و آن‌ها را مدیریت کرد:

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

افزودن و مدیریت کردن بازخوانی‌های ضربه زدن روی کارت

فراخوانی‌های برگشتی ضربه زدن روی کارت باید به‌طور جداگانه برای هر مؤلفه «کیت میانای کاربر» پیکربندی و مدیریت شود.

از اصلاح‌کننده .onTap در مؤلفه UI Kit برای مدیریت ضربه‌ها روی بدنه کارت استفاده کنید. وقتی کاربر روی کارت تک‌ضرب می‌زند، .onTap ساختار Place را که با سه ویژگی پر شده است ارسال می‌کند:

  • place.placeID (String?): «شناسه مکان» یکتا برای مثال، برای باز کردن برگه کامل PlaceDetailsView یا انتخاب نشانگر.
  • place.location (CLLocationCoordinate2D): مختصات طول/عرض جغرافیایی مکان برای مثال، برای قرار دادن دوربین نقشه در مرکز یا قرار دادن نشانگر.
  • ‫place.viewportInfo (RectangularCoordinateRegion?): مرزهای نمای نقشه توصیه‌شده (مختصات northEast و southWest) برای قاب‌بندی مکان روی نقشه.

کد زیر نحوه افزودن و مدیریت کردن فراخوان برگشتی تک‌ضرب روی کارت را برای 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)")
      }
    }
  }
}