เพิ่มข้อมูลวิเคราะห์ลงในคอมโพเนนต์ Places UI Kit

คุณสามารถสมัครรับข้อมูลเหตุการณ์ Analytics เกี่ยวกับผู้ใช้ที่แตะเส้นทาง โทร หรือเว็บไซต์, เปิด Google Maps, แตะการให้ดาวหรือการระบุแหล่งที่มาของผู้เขียน, เปิดไลท์บ็อกซ์รูปภาพ หรือเปลี่ยนแท็บ แต่ละเหตุการณ์จะระบุคอมโพเนนต์และประเภทเนื้อหาที่เริ่มทำงาน รวมถึงรหัสสถานที่และตำแหน่ง

เหตุการณ์ Analytics ที่ระบุ

ตารางต่อไปนี้แสดงตัวอย่างเหตุการณ์การวิเคราะห์ที่ Places UI Kit มีให้

การโต้ตอบกับ UI 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"
เปิดเมนูรายการเพิ่มเติมของไลท์บ็อกซ์ (⋮) แล้ว (ในแอป) {"click", "lightbox_menu"} "media"
เปิดเมนูสรุปแบบ Generative (⋮) แล้ว (ในแอป) {"click", "generative_summary_menu"} "generative_summary"
เปิดเมนูสรุปรีวิวแบบ Generative (⋮) แล้ว (ในแอป) {"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

คุณสามารถสมัครรับเหตุการณ์ Analytics จากคอมโพเนนต์ UI Kit ได้โดยใช้ตัวแก้ไข onPlaceAnalyticsEvent คุณสามารถแนบตัวแก้ไขกับมุมมองคอนเทนเนอร์หรือแนบกับคอมโพเนนต์ 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 2 รายการ) การแนบ .onPlaceAnalyticsEvent กับแต่ละมุมมองโดยตรงจะช่วยให้คุณทราบว่าอินสแตนซ์การ์ดใดที่ทริกเกอร์เหตุการณ์

ข้อมูลโค้ดต่อไปนี้แสดงวิธีสมัครรับและจัดการเหตุการณ์ Analytics โดยตรงในคอมโพเนนต์ 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")
        }
      }
  }
}

เพิ่มและจัดการ Callback การแตะบัตร

คุณต้องกำหนดค่าและจัดการ Callback การแตะบัตรแยกกันสำหรับคอมโพเนนต์ UI Kit แต่ละรายการ

ใช้ตัวแก้ไข .onTap ในคอมโพเนนต์ UI Kit เพื่อจัดการการแตะบนเนื้อหาของการ์ด เมื่อผู้ใช้แตะบัตร .onTap จะส่งโครงสร้าง Place ที่มีพร็อพเพอร์ตี้ 3 รายการดังนี้

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