장소 UI 키트 구성요소에 분석 추가

사용자가 경로, 통화 또는 웹사이트를 탭하거나, Google 지도를 열거나, 별표 평점 또는 작성자 저작자 표시를 탭하거나, 사진 라이트박스를 열거나, 탭을 전환하는 것과 관련된 분석 이벤트를 구독할 수 있습니다. 각 이벤트에는 실행된 구성요소와 콘텐츠 유형, 장소 ID, 위치가 표시됩니다.

제공되는 애널리틱스 이벤트

다음 표에는 장소 UI 키트에서 제공하는 분석 이벤트의 예가 나와 있습니다.

UI 상호작용 tags: Set<String> 연결된 콘텐츠/콘텐츠 유형
경로 버튼 {"click", "directions", "outbound"} "main_action_button" 또는 "corner_action_button"
지도에서 열기 버튼 {"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"
생성형 요약 메뉴(⋮)가 열림(앱 내) {"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))"
  )
}

애널리틱스 이벤트 구독 및 처리

onPlaceAnalyticsEvent 수정자를 사용하여 UI Kit 구성요소에서 분석 이벤트를 구독할 수 있습니다. 수정자를 컨테이너 뷰에 연결하거나 UI 키트 구성요소에 직접 연결할 수 있습니다.

다음 코드는 컨테이너 뷰 내에서 분석 이벤트를 구독하고 처리하는 방법을 보여줍니다.

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를 직접 연결하면 이벤트를 트리거한 특정 카드 인스턴스를 알 수 있습니다.

다음 코드 스니펫은 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")
        }
      }
  }
}

카드 탭 콜백 추가 및 처리

카드 탭 콜백은 각 UI 키트 구성요소에 대해 별도로 구성하고 처리해야 합니다.

UI 키트 구성요소에서 .onTap 수정자를 사용하여 카드 본문 탭을 처리합니다. 사용자가 카드를 탭하면 .onTap는 세 가지 속성으로 채워진 Place 구조체를 전달합니다.

  • place.placeID(String?): 전체 PlaceDetailsView 시트를 열거나 마커를 선택하는 등의 작업을 위한 고유한 장소 ID입니다.
  • 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)")
      }
    }
  }
}