افزودن Analytics به مؤلفه «کیت میانای کاربر جاها»

می‌توانید در رویدادهای تجزیه‌وتحلیل مربوط به تک‌ضرب زدن کاربران روی «مسیرها»، «تماس»، یا «وب‌سایت»، باز کردن Google Maps، تک‌ضرب زدن روی رده‌بندی ستاره یا ارجاع به نویسنده، باز کردن لایت‌باکس عکس، یا جابه‌جا شدن بین برگه‌ها مشترک شوید. هر رویداد می‌گوید کدام مؤلفه و نوع محتوا فعال شده است، و همچنین شناسه مکان و موقعیت مکانی را نشان می‌دهد.

رویدادهای Analytics که ارائه شده است

جدول زیر نمونه‌هایی از رویدادهای تجزیه‌وتحلیل را که توسط «کیت میانای کاربر جاها» ارائه می‌شود نشان می‌دهد.

تعامل با میانای کاربر 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"
منوِ سرریز Lightbox (⋮) باز شد (درون‌برنامه) {"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...
}

مشترک شدن در رویدادهای Analytics و مدیریت آن‌ها

می‌توانید با پیچیدن محفظه چیدمان ولی یا خود مؤلفه در ProvidePlacesAnalyticsHandler، در رویدادهای Analytics از مؤلفه UI Kit Compose مشترک شوید.

کد زیر نحوه مشترک شدن و مدیریت رویدادهای Analytics را در سلسله‌مراتب محفظه نشان می‌دهد:

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 composable)، با قرار دادن هر composable در ProvidePlacesAnalyticsHandler خودش می‌توانید متوجه شوید کدام نمونه کارت خاص رویداد را راه‌اندازی کرده است.

تکه‌کد زیر نحوه مشترک شدن و مدیریت رویدادهای Analytics را برای یک 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"}")
      }
    )
  }
}

افزودن و مدیریت کردن بازخوانی‌های ضربه زدن روی کارت

فراخوانی‌های برگشتی ضربه زدن روی کارت باید به‌طور جداگانه برای هر مؤلفه «کیت میانای کاربر» پیکربندی و مدیریت شود.

از پارامتر onClick در UI Kit composable برای مدیریت ضربه زدن روی بدنه کارت استفاده کنید. وقتی کاربر روی کارت ضربه می‌زند، onClick شیء Place را که با سه ویژگی پر شده است ارسال می‌کند:

  • ‫place.id (String?): «شناسه جا» منحصربه‌فرد برای مثال، برای باز کردن نمای کامل «جزئیات جا» یا انتخاب نشانگر.
  • place.location (LatLng?): مختصات طول/عرض جغرافیایی مکان برای مثال، برای قرار دادن دوربین نقشه در مرکز یا قرار دادن نشانگر.
  • ‫place.viewport (LatLngBounds?): مرزهای نمای نقشه توصیه‌شده (مختصات northeast و southwest) برای قاب‌بندی مکان روی نقشه.

کد زیر نحوه افزودن و مدیریت کردن فراخوانی برگشتی ضربه زدن روی کارت را برای یک AdvancedPlaceDetailsCompact composable نشان می‌دهد:

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