إضافة إحصاءات إلى أحد مكوّنات حزمة أدوات "خرائط 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}") } } ) }