เพิ่มข้อมูลวิเคราะห์ลงในคอมโพเนนต์ Places UI Kit

คุณสามารถสมัครรับข้อมูลเหตุการณ์ Analytics เกี่ยวกับผู้ใช้ที่แตะเส้นทาง โทร หรือเว็บไซต์, เปิด Google Maps, แตะการให้ดาวหรือการระบุแหล่งที่มาของผู้เขียน, เปิดไลท์บ็อกซ์รูปภาพ หรือเปลี่ยนแท็บ แต่ละเหตุการณ์จะระบุคอมโพเนนต์และประเภทเนื้อหาที่เริ่มทำงาน รวมถึงรหัสสถานที่และตำแหน่ง

เหตุการณ์ Analytics ที่ระบุ

ตารางต่อไปนี้แสดงตัวอย่างเหตุการณ์การวิเคราะห์ที่ Places UI Kit มีให้

การโต้ตอบกับ UI 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"
เปิดเมนูรายการเพิ่มเติมของไลท์บ็อกซ์ (⋮) แล้ว (ในแอป) {"click", "lightbox_menu"} "media"
เปิดเมนูสรุปแบบ Generative (⋮) แล้ว (ในแอป) {"click", "generative_summary_menu"} "generative_summary"
เปิดเมนูสรุปรีวิวแบบ Generative (⋮) แล้ว (ในแอป) {"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

คุณสามารถสมัครรับเหตุการณ์ Analytics จากคอมโพเนนต์ Compose ของ UI Kit ได้โดยรวมคอนเทนเนอร์เลย์เอาต์หลักหรือคอมโพเนนต์ไว้ใน ProvidePlacesAnalyticsHandler

โค้ดต่อไปนี้แสดงวิธีสมัครรับข้อมูลและจัดการเหตุการณ์ 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 2 รายการ) การรวมคอมโพสิเบิลแต่ละรายการไว้ใน ProvidePlacesAnalyticsHandler ของตัวเองจะช่วยให้คุณทราบว่าอินสแตนซ์การ์ดใดที่ทริกเกอร์เหตุการณ์

ข้อมูลโค้ดต่อไปนี้แสดงวิธีสมัครรับข้อมูลและจัดการเหตุการณ์ Analytics สำหรับ Composable ของ 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"}")
      }
    )
  }
}

เพิ่มและจัดการ Callback การแตะบัตร

คุณต้องกำหนดค่าและจัดการ Callback การแตะบัตรแยกกันสำหรับคอมโพเนนต์ UI Kit แต่ละรายการ

ใช้พารามิเตอร์ onClick ใน UI Kit Composable เพื่อจัดการการแตะที่เนื้อหาการ์ด เมื่อผู้ใช้แตะบัตร onClick จะส่งออบเจ็กต์ Place ที่มีพร็อพเพอร์ตี้ 3 รายการดังนี้

  • place.id (String?): รหัสสถานที่ที่ไม่ซ้ำกัน เช่น เพื่อเปิดมุมมองรายละเอียดสถานที่แบบเต็มหรือเลือกเครื่องหมาย
  • place.location (LatLng?): พิกัดละติจูด/ลองจิจูดของสถานที่ เช่น เพื่อจัดกึ่งกลางกล้องแผนที่หรือวางเครื่องหมาย
  • place.viewport (LatLngBounds?): ขอบเขตวิวพอร์ตแผนที่ที่แนะนำ (พิกัด northeast และ southwest) สำหรับการจัดเฟรมสถานที่บนแผนที่

โค้ดต่อไปนี้แสดงวิธีเพิ่มและจัดการ Callback การแตะบัตรสำหรับ 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}")
      }
    }
  )
}