הוספת ניתוח נתונים לרכיב של Places UI Kit

אתם יכולים להירשם לאירועי ניתוח נתונים שקשורים למשתמשים שלוחצים על "מסלול", "התקשרות" או "אתר", פותחים את מפות Google, לוחצים על דירוג הכוכבים או על שיוך ליוצר, פותחים את תיבת ה-Lightbox של התמונות או מחליפים כרטיסיות. בכל אירוע מצוין איזה רכיב וסוג תוכן הופעלו, וגם מזהה המקום והמיקום.

אירועים ב-Analytics שמוצגים

בטבלה הבאה מפורטות דוגמאות לאירועי ניתוח נתונים שמתקבלים מ-Places UI Kit.

אינטראקציה עם ממשק המשתמש tags: Set<String> תוכן משויך/סוג תוכן
כפתור מסלול הגעה {"click", "directions", "outbound"} "main_action_button" או "corner_action_button"
כפתור לפתיחה במפות Google {"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"
קישור לשיוך (Attribution) {"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"
פתיחת תמונה ב-Lightbox (בתוך האפליקציה) {"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"
תפריט סיכום של ביקורות שנוצר על ידי AI‏ (⋮) נפתח (בתוך האפליקציה) {"click", "review_summary_menu"} "review"

יכול להיות שעם הזמן יתווספו אירועים ותגים חדשים, לכן אתם יכולים לצרף handler כללי במהלך הפיתוח כדי לתעד כל אירוע שמשודר כשאתם יוצרים אינטראקציה עם רכיב:

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

הרשמה לאירועי ניתוח נתונים וטיפול בהם

אפשר להירשם לאירועי ניתוח נתונים מרכיב של ערכת ממשק המשתמש באמצעות המשתנה onPlaceAnalyticsEvent. אפשר לצרף את ה-modifier לתצוגת קונטיינר או ישירות לרכיב של ערכת ממשק המשתמש.

הקוד הבא מראה איך להירשם לאירועי ניתוח נתונים ולטפל בהם בתצוגת קונטיינר:

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:

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) של לחיצה על כרטיס

צריך להגדיר ולטפל בקריאות חוזרות (callbacks) של לחיצה על כרטיס בנפרד לכל רכיב של ערכת ממשק המשתמש.

כדי לטפל בהקשות על גוף הכרטיס, משתמשים ב-modifier‏ .onTap ברכיב של ערכת ממשק המשתמש. כשהמשתמש לוחץ על הכרטיס, .onTap מעביר מבנה Place שמאוכלס בשלושה מאפיינים:

  • ‫place.placeID (String?): מזהה המקום הייחודי, למשל כדי לפתוח גיליון PlaceDetailsView מלא או לבחור סמן.
  • ‫place.location (CLLocationCoordinate2D): קואורדינטות קו הרוחב/קו האורך של המקום, למשל כדי למרכז את מצלמת המפה או להציב סמן.
  • ‫place.viewportInfo (RectangularCoordinateRegion?): הגבולות המומלצים של אזור התצוגה במפה (הקואורדינטות northEast ו-southWest) כדי להציג את המקום במפה.

הקוד הבא מראה איך להוסיף ולטפל בקריאה חוזרת (callback) של לחיצה על כרטיס של 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)")
      }
    }
  }
}