Componente Advanced Place Details

La versión Advanced del componente Place Details ofrece las mismas funciones que Place Details Essentials. También te permite configurar los botones de acción del componente y aplicar opciones de búsqueda y filtrado a las opiniones y el contenido multimedia que se muestran.

Compatibilidad integrada con Jetpack Compose

El kit de IU de Places proporciona funciones de Jetpack Compose @Composable para AdvancedPlaceDetailsCompact. Estos elementos que admiten composición usan el estado elevado, la compatibilidad con modificadores integrados y los DSL de ranuras nativos de Compose.

En la siguiente muestra de código, se indica cómo usar la función de componibilidad para un diseño vertical.

Kotlin

import android.util.Log
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.painter.Painter
import androidx.compose.ui.unit.dp
import com.google.android.libraries.places.api.model.Place
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.PlaceReference
import com.google.android.libraries.places.compose.action.CornerAction
import com.google.android.libraries.places.compose.action.MainAction
import com.google.android.libraries.places.compose.Orientation

@Composable
fun SampleAdvancedPlaceDetailsCompactCard(
    placeId: String,
    bookmarkIcon: Painter,
    onSavePlaceClicked: (Place) -> Unit
) {
    AdvancedPlaceDetailsCompact(
        // defines the place to be displayed
        reference = PlaceReference.PlaceId(placeId),
        // defines the orientation
        orientation = Orientation.VERTICAL,
        // defines custom styling
        modifier = Modifier
            .fillMaxWidth()
            .padding(16.dp),
        preferTruncation = true,
        enableLightbox = true,
        mainActions = { place ->
            listOf(
                MainAction.OpenDirections(),
                MainAction.OpenWebsite(),
                MainAction.Call()
            )
        },
        // action button configuration
        cornerActions = { place ->
            listOf(
                CornerAction.Custom(
                    icon = bookmarkIcon,
                    text = "Save Place",
                    onClick = { onSavePlaceClicked(place) }
                )
            )
        },
        onPlaceLoaded = { place ->
            Log.d("Places", "Successfully loaded place: ${place.id}")
        },
        onPlaceLoadFailed = { exception ->
            Log.e("Places", "Failed to load place", exception)
        }
    ) {
        // --- Slot: Injected directly above the place name ---
        basicSectionTop {
            Text(
                text = "Featured in 'Top 10 Coffee Shops in SF'",
                style = MaterialTheme.typography.labelSmall,
                color = MaterialTheme.colorScheme.secondary,
                modifier = Modifier.padding(top = 4.dp, bottom = 2.dp)
            )
        }

        // --- Slot: Injected directly below the action buttons ---
        basicSectionBottom {
            Text(
                text = "Notes: Great quiet atmosphere for meetings.",
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.onSurfaceVariant
            )
        }
    }
}

Configuración avanzada de Place Details

Usa AdvancedPlaceDetailsFragment o AdvancedPlaceDetailsCompactFragment para acceder a las funciones avanzadas.

Cómo configurar botones de acción

Usa la interfaz PlaceActionProvider de AdvancedPlaceDetailsFragment o AdvancedPlaceDetailsCompactFragment para definir y personalizar los botones de acción.

Si usas funciones de @composable, usa las lambdas mainActions y cornerActions para configurar los botones de acción.

Requisitos de atribución visual

Vista compacta de Place Details con botones personalizados
Vista compacta de Advanced Place Details con un botón personalizado

Importante: Debes dejar en claro a los usuarios finales cuando un botón de acción personalizada comparta información del usuario con un tercero que no sea Google. Consulta los requisitos de atribución visual.

En el ejemplo de la derecha, se muestra una imagen personalizada que deja en claro que la información del usuario se enviará a "Altostrat".

Aplicar opciones de búsqueda y filtrado

Usa las clases SearchMediaOptions y SearchReviewsOptions de AdvancedPlaceDetailsFragment o AdvancedPlaceDetailsCompactFragment para habilitar la búsqueda y el filtrado de contenido multimedia o de opiniones.

Si usas funciones @composable, usa com.google.android.libraries.places.compose.search.SearchMediaOptions para habilitar la búsqueda y el filtrado de contenido multimedia o de opiniones.

Crea espacios de contenido personalizados

Opciones de posición de espacios publicitarios de contenido personalizado

Los espacios de contenido personalizado te permiten agregar tu propio contenido (como resúmenes generados por IA, marcas de tiempo de itinerarios o insignias personalizadas) directamente en zonas de diseño predefinidas.

Requisitos de atribución y sugerencias de contenido para los espacios de contenido

Cuando se activa un espacio de contenido personalizado, la divulgación se actualiza automáticamente para aclarar qué contenido proporciona Google y qué contenido proporcionan terceros.

Qué debes hacer

Mantén una jerarquía visual clara entre los detalles de Google Place y el contenido personalizado para evitar cualquier ambigüedad sobre la fuente de la información.

Evita la ambigüedad sobre la fuente de información

Qué debes hacer

Considera proporcionar estadísticas localizadas y de gran valor adaptadas a los objetivos inmediatos de tus usuarios. El contenido personalizado, como los períodos de reserva en tiempo real o la disponibilidad actual, ayuda a los usuarios a tomar decisiones más rápidas y fundamentadas.

Proporciona estadísticas de gran valor

Qué no debes hacer

No dupliques los detalles existentes de Google Place, como las calificaciones, las opiniones o el horario de atención, incluso si ocultaste el contenido proporcionado por Google. Si lo haces, los usuarios podrían confundirse sobre la fuente del contenido y si proviene de Google o de un tercero.

No dupliques los detalles de un lugar de Google existente

Qué no debes hacer

No muestres afirmaciones ni insignias sin atribución (por ejemplo, "¡La mejor recomendación!") que puedan confundirse con respaldos oficiales de Google. El contenido personalizado debe atribuir explícitamente su fuente.

No muestres afirmaciones o insignias sin atribución

Qué no debes hacer

No incluyas anuncios, textos de marketing, descuentos promocionales ni mensajes de suscripción en los contenedores de lugares personalizados.

No incluyas anuncios, textos de marketing, descuentos promocionales ni mensajes de suscripción

Para agregar contenido personalizado, usa el elemento que admite composición AdvancedPlaceDetailsCompact. Usa basicSectionTop o basicSectionBottom para especificar la posición del contenido.

Ejemplos avanzados de Place Details

Cómo personalizar los botones de acción

Usa la interfaz PlaceActionProvider para controlar qué acciones están disponibles para cada lugar.

Kotlin

class PlaceDetailsWidgetTestActivity : BaseActivity() {

// simplified example of starting the fragment
fun setupPPDFragment() {
   fullWidgetSelectedContent = AdvancedPlaceDetailsFragment.ALL_CONTENT.toMutableList()
   AdvancedPlaceDetailsFragment.newInstance(fullWidgetSelectedContent, Orientation.VERTICAL)
   supportFragmentManager
      .beginTransaction()
      .replace(R.id.fragment_container, fragment!!)
      .commitNow()
}

// you can set the callback elsewhere, but this is the ideal callback spot
override fun onAttachFragment(fragment: Fragment) {
    super.onAttachFragment(fragment)
    when (fragment) {
      is PlaceActionController -> setPlaceActionProvider(fragment)
    }
}

// have this callback return an empty list to hide all buttons
// if this callback isn't set, default buttons appear
 private fun setPlaceActionProvider(fragment: PlaceActionController) {
    fragment.setPlaceActionProvider(
        object : PlaceActionProvider {
        override fun getMainPlaceActions(place: Place): List<PlaceAction> = buildList {
            // predefined actions can be mixed in with custom ones
            add(PlaceAction.OPEN_IN_MAPS)

            // example of button with both text label and icon
            add(
              PlaceAction.builder()
                .setLabelTextResId(R.string.custom_action)
                .setIconResId(R.drawable.gs_custom_action_icon)
                .setContentDescriptionResId(R.string.custom_action_description)
                .setOnClickListener { /* todo perform action */ }
                .build()
            )

            // icon only button
            add(
              PlaceAction.builder()
                .setIconResId(R.drawable.custom_action_icon_2)
                .setContentDescriptionResId(R.string.custom_action_description_2)
                .setOnClickListener { /* todo perform action */}
                .build()
            )

            // text label only button
            add(
              PlaceAction.builder()
                .setLabelTextResId(R.string.custom_action_3)
                .setContentDescriptionResId(R.string.custom_action_description_2)
                .setOnClickListener {/* todo perform action */ }
                .build()
            )
          }

         /**
         You can also specify whether corner buttons should appear.  
         For either callback, returning an empty list results in no buttons appearing
         */
         override fun getCornerPlaceActions(place: Place): List<PlaceAction> {
           return emptyList()
         }

        override fun addPlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          // in this example, just one listener and widget
          this@HostAppActivity.listener = listener
        }

        override fun removePlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          // if there are multiple listeners, remove only the provided listener
          this@HostAppActivity.listener = null
        }
      })
  }
}

Agrega acciones personalizadas y predefinidas

En este ejemplo, se agrega un botón de activación para que un usuario agregue un lugar a favoritos o lo quite de esa categoría.

Kotlin

private var listener: PlaceActionProvider.OnChangedListener? = null

private fun setPlaceActionProvider(fragment: PlaceActionController) {
    fragment.setPlaceActionProvider(
      object : PlaceActionProvider {
        private var placeFavorited = false

        override fun getMainPlaceActions(place: Place): List<PlaceAction> {
          val buttonList = mutableListOf<PlaceAction>()

          if (placeFavorited) {
            buttonList.add(
              PlaceAction.builder()
                .setLabelTextResId(R.string.place_details_button_config_favorite)
                .setIconResId(R.drawable.gs_web_vd_theme_24)
                .setOnClickListener {
                  placeFavorited = !placeFavorited
                  refreshButtonConfigs()
                }
                .build()
            )
          } else {
            buttonList.add(
              PlaceAction.builder()
                .setLabelTextResId(R.string.place_details_button_config_unfavorite)
                .setIconResId(R.drawable.gs_web_vd_theme_24)
                .setOnClickListener {
                  placeFavorited = !placeFavorited
                  refreshButtonConfigs()
                }
                .build()
            )
          }

          return buttonList
        }

        override fun addPlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          this@PlaceDetailsWidgetTestActivity.listener = listener
        }

        override fun removePlaceActionsChangedListener(
          listener: PlaceActionProvider.OnChangedListener
        ) {
          // if there are multiple listeners, remove only the provided listener
          this@PlaceDetailsWidgetTestActivity.listener = null
        }
      }
    )
  }

private fun refreshButtonConfigs() {
    listener?.onPlaceActionsChanged()
}

Usa botones estándar predefinidos

Crea botones de acción que realicen acciones estándar definidas por Google.

Kotlin

  override fun getMainPlaceActions(place: Place): List<PlaceAction> {
    val buttonList = mutableListOf<PlaceAction>()
// these buttons will have different background and text color than user-created buttons.  
    // Text and icon button
    buttonList.add(PlaceAction.OPEN_IN_MAPS)
    // Icon-only buttons not enabled for main action buttons
    // Use of kotlin extension to do the same.  see
    PlaceAction.OPEN_IN_MAPS {
       setIconResId(0)
     }

    return buttonList
  }

Cómo filtrar opiniones y contenido multimedia

En esta muestra de código, solo se muestran el contenido multimedia y las opiniones que mencionan "espagueti" y "sabroso".

Kotlin

    import com.google.android.libraries.places.widget.AdvancedPlaceDetailsFragment
    import com.google.android.libraries.places.widget.model.SearchMediaOptions
    import com.google.android.libraries.places.widget.model.SearchReviewsOptions
    import com.google.android.libraries.places.widget.model.Orientation
    import com.google.android.libraries.places.R
  
     // 1. Create options using the Java builders (called from Kotlin)
    val mediaOptions = SearchMediaOptions.builder()
        .setQuery("spaghetti")
        .setRankPreference(SearchMediaOptions.RankPreference.MOST_RELEVANT)
        .build()

    val reviewOptions = SearchReviewsOptions.builder()
        .setQuery("tasty")
        .setRankPreference(SearchReviewsOptions.RankPreference.NEWEST)
        .build()

    // 2. Create the fragment
    val fragment = AdvancedPlaceDetailsFragment.newInstance(
        AdvancedPlaceDetailsFragment.STANDARD_CONTENT,
        Orientation.VERTICAL,
        R.style.PlacesMaterialTheme
    )

    // 3. Apply options to the fragment
    fragment.applySearchMediaOptions(mediaOptions)
    fragment.applySearchReviewsOptions(reviewOptions)

Cómo crear espacios de contenido

Kotlin

import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import com.google.android.libraries.places.compose.AdvancedPlaceDetailsCompact
import com.google.android.libraries.places.compose.PlaceReference

@Composable
fun ItineraryPlaceCard(placeId: String) {
    AdvancedPlaceDetailsCompact(
        reference = PlaceReference.PlaceId(placeId)
    ) {
        // Slot: Injected directly above the place name
        basicSectionTop {
            Text(
                text = "Day 2 • 2:30 PM",
                style = MaterialTheme.typography.labelSmall,
                color = MaterialTheme.colorScheme.primary
            )
        }
        
        // Slot: Injected directly below the main action buttons
        basicSectionBottom {
            NotesCard(
                notes = "Great quiet atmosphere for morning meetings. Famous for house-roasted pour-overs."
            )
        }
    }
}