הוספת ניתוח נתונים לרכיב של 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}")
      }
    }
  )
}