הוספת ניתוח נתונים לרכיב של Places UI Kit
אתם יכולים להירשם לאירועי ניתוח נתונים שקשורים למשתמשים שלוחצים על "מסלול", "התקשרות" או "אתר", פותחים את מפות Google, לוחצים על דירוג הכוכבים או על שיוך ליוצר, פותחים את תיבת ה-Lightbox של התמונות או מחליפים כרטיסיות. בכל אירוע מצוין איזה רכיב וסוג תוכן הופעלו, וגם מזהה המקום והמיקום.
אירועים ב-Analytics שמופיעים
בטבלה הבאה מפורטות דוגמאות לאירועי ניתוח נתונים שמתקבלים מ-Places UI Kit.
| אינטראקציה עם ממשק המשתמש | 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" |
| קישור לשיוך (Attribution) | {"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" |
| פתיחת תמונה ב-Lightbox (בתוך האפליקציה) | {"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" |
תפריט סיכום של ביקורות שנוצר על ידי AI (⋮) נפתח (בתוך האפליקציה) |
{"click", "review_summary_menu"} |
"review" |
יכול להיות שעם הזמן יתווספו אירועים ותגים חדשים, לכן אתם יכולים לצרף handler כללי במהלך הפיתוח כדי לתעד כל אירוע שמשודר כשאתם יוצרים אינטראקציה עם רכיב:
// 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"}") } ) } }
הוספה וטיפול בקריאות חוזרות (callbacks) של לחיצה על כרטיס
צריך להגדיר ולטפל בקריאות חוזרות (callbacks) של לחיצה על כרטיס בנפרד לכל רכיב של ערכת ממשק המשתמש.
משתמשים בפרמטר onClick ברכיב ה-composable של ערכת ממשק המשתמש כדי לטפל בהקשות על גוף הכרטיס. כשהמשתמש לוחץ על הכרטיס, onClick מעביר אובייקט Place שמאוכלס בשלושה מאפיינים:
-
place.id(String?): מזהה המקום הייחודי, למשל כדי לפתוח תצוגה מלאה של Place Details או לבחור סמן. -
place.location(LatLng?): קואורדינטות קו הרוחב/קו האורך של המקום, למשל כדי למרכז את מצלמת המפה או להציב סמן. -
place.viewport(LatLngBounds?): הגבולות המומלצים של אזור התצוגה במפה (הקואורדינטותnortheastו-southwest) כדי להציג את המקום במפה.
הקוד הבא מראה איך להוסיף ולטפל בקריאה חוזרת (callback) של לחיצה על כרטיס עבור פונקציה קומפוזבילית 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}") } } ) }