장소 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"

시간이 지남에 따라 새로운 이벤트와 태그가 추가될 수 있으므로 개발 중에 일반 핸들러를 연결하여 구성요소와 상호작용할 때 브로드캐스트되는 모든 이벤트를 로깅할 수 있습니다.

// Wrap your Places UI Kit composable or parent layout to inspect all broadcast events.
// AnalyticsEvent.toString() includes componentType, tags, place IDs, and contentType.
ProvidePlacesAnalyticsHandler(
  handler = { event ->
    Log.d("PlacesAnalytics", "$event")
  }
) {
  // Places UI Kit composables...
}

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

상위 요소 레이아웃 컨테이너 또는 구성요소 자체를 ProvidePlacesAnalyticsHandler로 래핑하여 UI Kit Compose 구성요소에서 분석 이벤트를 구독할 수 있습니다.

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

import android.util.Log
import androidx.compose.foundation.layout.Column
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.AnalyticsEvent
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.PlaceReference
import com.google.android.libraries.places.compose.ProvidePlacesAnalyticsHandler
import com.google.firebase.*

@Composable
fun PlaceCardScreen() {
  val placeRef = PlaceReference.PlaceId("ChIJN1t_tDeuEmsRUsoyG83frY4")

  // Analytics callback wraps the container hierarchy
  ProvidePlacesAnalyticsHandler(
    handler = { event ->
      val placeId = event.places.firstOrNull()?.id ?: "none"

      // Option A: Check for specific interactions using built-in Tags constants
      if (AnalyticsEvent.Tags.DIRECTIONS in event.tags) {
        Log.d("PlacesAnalytics", "User requested directions for place: $placeId")
      }

      if (AnalyticsEvent.Tags.OUTBOUND in event.tags) {
        Log.d(
          "PlacesAnalytics",
          "User is leaving the app via: ${event.tags.sorted().joinToString(", ")}"
        )
      }

      // Option B: Forward every event directly to your analytics SDK (e.g., Firebase)
      val firebaseAnalytics = remember { Firebase.analytics }
      firebaseAnalytics.logEvent("place_ui_kit_interaction") {
        param("component_type", event.componentType)
        param("content_type", event.contentType ?: "none")
        param("tags", event.tags.sorted().joinToString(","))
        param("place_id", placeId)
      }
    }
  ) {
    Column {
      AdvancedPlaceDetailsCompact(
        reference = placeRef,
        // Direct card tap (for UI navigation, e.g., centering a map)
        onClick = { place ->
          Log.d("Places", "Card tapped for place ID: ${place.id ?: "unknown"}")
        }
      )
    }
  }
}

앱에 동일한 위젯 유형의 카드가 여러 개 표시되는 경우(예: AdvancedPlaceDetailsCompact 컴포저블 2개) 각 컴포저블을 자체 ProvidePlacesAnalyticsHandler로 래핑하면 이벤트를 트리거한 특정 카드 인스턴스를 알 수 있습니다.

다음 코드 스니펫은 단일 AdvancedPlaceDetailsCompact 컴포저블의 분석 이벤트를 구독하고 처리하는 방법을 보여줍니다.

import android.util.Log
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.AnalyticsEvent
import com.google.android.libraries.places.compose.Orientation
import com.google.android.libraries.places.compose.PlaceReference
import com.google.android.libraries.places.compose.ProvidePlacesAnalyticsHandler

@Composable
fun SinglePlaceCardView() {
  val placeRef = PlaceReference.PlaceId("ChIJN1t_tDeuEmsRUsoyG83frY4")

  // Analytics callback scoped to this specific composable instance
  ProvidePlacesAnalyticsHandler(
    handler = { event ->
      val placeIds = event.places.mapNotNull { it.id }.joinToString(", ")
      val tags = event.tags.sorted().joinToString(", ")

      Log.d(
        "PlacesAnalytics",
        "[$tags] in ${event.componentType}, content: ${event.contentType ?: "null"}, places: [$placeIds]"
      )

      if (AnalyticsEvent.Tags.DIRECTIONS in event.tags) {
        Log.d("PlacesAnalytics", "Directions tapped on this card")
      }
    }
  ) {
    AdvancedPlaceDetailsCompact(
      reference = placeRef,
      orientation = Orientation.HORIZONTAL,
      // Direct card-tap callback
      onClick = { place ->
        Log.d("Places", "Tapped card for place: ${place.id ?: "unknown"}")
      }
    )
  }
}

카드 탭 콜백 추가 및 처리

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

UI 키트 컴포저블에서 onClick 매개변수를 사용하여 카드 본문 탭을 처리합니다. 사용자가 카드를 탭하면 onClick에서 세 가지 속성으로 채워진 Place 객체를 전달합니다.

  • place.id(String?): 고유한 장소 ID입니다(예: 전체 장소 세부정보 뷰를 열거나 마커를 선택하는 데 사용).
  • place.location(LatLng?): 장소의 위도/경도 좌표입니다(예: 지도 카메라를 중앙에 배치하거나 마커를 배치하는 경우).
  • place.viewport(LatLngBounds?): 지도에서 장소를 프레이밍하기 위한 권장 지도 표시 영역 경계(northeast 및 southwest 좌표)입니다.

다음 코드는 AdvancedPlaceDetailsCompact 컴포저블에 카드 탭 콜백을 추가하고 처리하는 방법을 보여줍니다.

import android.util.Log
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import com.google.android.libraries.places.api.model.Place
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.Orientation
import com.google.android.libraries.places.compose.PlaceReference

@Composable
fun PlaceCardTapSampleView() {
  val peetsCoffeePlaceId = "ChIJT7FdmYiAhYAROFOvrIxRJDU"
  var selectedPlace by remember { mutableStateOf<Place?>(null) }

  AdvancedPlaceDetailsCompact(
    reference = PlaceReference.PlaceId(peetsCoffeePlaceId),
    orientation = Orientation.HORIZONTAL,
    onClick = { place ->
      // Handle the card tap using place.id, place.location, or place.viewport
      selectedPlace = place
      Log.d("Places", "Tapped place ID: ${place.id ?: "unknown"}")

      place.location?.let { location ->
        Log.d("Places", "Coordinates: ${location.latitude}, ${location.longitude}")
      }

      place.viewport?.let { viewport ->
        Log.d("Places", "Viewport NE: ${viewport.northeast}, SW: ${viewport.southwest}")
      }
    }
  )
}