إضافة إحصاءات إلى أحد مكوّنات حزمة أدوات "خرائط Google" الجاهزة للأماكن

يمكنك الاشتراك في أحداث الإحصاءات حول نقر المستخدمين على "الاتجاهات" أو "اتصال" أو "الموقع الإلكتروني" أو فتح "خرائط Google" أو النقر على التقييم بالنجوم أو تحديد مصدر المؤلف أو فتح مربّع عرض الصور أو تبديل علامات التبويب. ويشير كل حدث إلى المكوّن ونوع المحتوى اللذين تم تشغيلهما، بالإضافة إلى رقم تعريف المكان وموقعه الجغرافي.

أحداث "إحصاءات Google" المقدَّمة

يقدّم الجدول التالي أمثلة على أحداث الإحصاءات التي توفّرها حزمة أدوات "خرائط Google" الجاهزة للأماكن.

التفاعل مع واجهة المستخدم tags: Set<String> المحتوى المرتبط/نوع المحتوى
زرّ الاتجاهات {"click", "directions", "outbound"} "main_action_button" أو "corner_action_button"
زر "فتح في خرائط Google" {"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...
}

الاشتراك في أحداث الإحصاءات ومعالجتها

يمكنك الاشتراك في أحداث الإحصاءات من مكوّن 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"}")
        }
      )
    }
  }
}

إذا كان تطبيقك يعرض بطاقات متعددة من نوع التطبيق المصغّر نفسه (على سبيل المثال، دالتان مركّبتان من النوع AdvancedPlaceDetailsCompact)، فإنّ تضمين كل دالة مركّبة في دالة 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 Kit.

استخدِم المَعلمة onClick في دالة مركّبة في UI Kit للتعامل مع النقرات على نص البطاقة. عندما ينقر المستخدم على البطاقة، يمرّر onClick عنصر Place يتضمّن ثلاث سمات:

  • ‫place.id (String?): رقم تعريف المكان الفريد، على سبيل المثال، لفتح عرض كامل لصفحة "تفاصيل المكان" أو اختيار علامة.
  • 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}")
      }
    }
  )
}