Как добавить аналитику в компонент Places UI Kit

Вы можете подписаться на события аналитики, связанные с тем, что пользователи нажимают "Маршрут", "Позвонить" или "Сайт", открывают Google Карты, нажимают на оценку или имя автора, открывают лайтбокс с фотографией или переключают вкладки. Для каждого события указывается, какой компонент и тип контента были активированы, а также идентификатор места и местоположение.

События Аналитики, которые предоставляются

В таблице ниже приведены примеры событий аналитики, которые предоставляет Places UI Kit.

Взаимодействие с интерфейсом 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...
}

Как подписаться на события аналитики и обрабатывать их

Вы можете подписаться на события аналитики из компонента Compose в UI Kit, поместив родительский контейнер макета или сам компонент в ProvidePlacesAnalyticsHandler.

В следующем примере кода показано, как подписаться на события аналитики и обрабатывать их в иерархии контейнеров:

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

Если в приложении показывается несколько карточек одного типа (например, две composable-функции AdvancedPlaceDetailsCompact), то, поместив каждую из них в отдельный элемент ProvidePlacesAnalyticsHandler, вы сможете узнать, какая именно карточка активировала событие.

В следующем фрагменте кода показано, как подписаться на события аналитики и обрабатывать их для одной composable-функции 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 Kit.

Используйте параметр onClick в composable-функции UI Kit, чтобы обрабатывать нажатия на карточку. Когда пользователь нажимает на карточку, onClick передает объект Place, заполненный тремя свойствами:

  • place.id (String?) – уникальный идентификатор места, который можно использовать, например, чтобы открыть полную информацию о месте или выбрать маркер.
  • place.location (LatLng?) – координаты широты и долготы места, например для центрирования камеры карты или размещения маркера.
  • place.viewport (LatLngBounds?) – рекомендуемые границы области просмотра карты (координаты northeast и southwest) для кадрирования места на карте.

В следующем коде показано, как добавить и обработать обратный вызов нажатия на карточку для composable-функции 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}")
      }
    }
  )
}