Composant Advanced Place Details
La version Advanced du composant Place Details offre les mêmes fonctionnalités que Places Details Essentials. Il vous permet également de configurer les boutons d'action du composant, et d'appliquer des options de recherche et de filtrage aux avis et aux contenus multimédias affichés.
Compatibilité intégrée avec Jetpack Compose
Le kit UI pour Places fournit des fonctions Jetpack Compose @Composable pour AdvancedPlaceDetailsCompact et AdvancedPlaceDetails. Ces composables utilisent l'état hissé, la compatibilité intégrée avec les modificateurs et les DSL d'emplacement natifs de Compose. Voir un exemple
Jetons pour les applications agentives
Le jeton de visualisation des données agentiques permet à votre application agentique d'afficher les éléments du Kit UI pour Places pour les lieux d'une réponse Maps Experience Agent Tools (anciennement Maps Grounding Lite) sans frais supplémentaires. Pour en savoir plus, consultez Jeton de visualisation des données agentique.
Configuration avancée de Place Details
Utilisez le composable AdvancedPlaceDetailsFragment, AdvancedPlaceDetailsCompactFragment, AdvancedPlaceDetails ou AdvancedPlaceDetailsCompact pour accéder aux fonctionnalités avancées.
Options d'affichage du contenu
Vous pouvez spécifier le contenu à afficher à l'aide des énumérations dans AdvancedPlaceDetailsFragment. Vous pouvez configurer le même contenu que pour Place Details Essentials. Si vous utilisez les fonctions composables, vous pouvez également choisir d'afficher ou non le nom du lieu.
Configurer les boutons d'action
Utilisez l'interface PlaceActionProvider de AdvancedPlaceDetailsFragment ou AdvancedPlaceDetailsCompactFragment pour définir et personnaliser les boutons d'action.
Si vous utilisez des fonctions @Composable, utilisez les lambdas mainActions et cornerActions pour configurer les boutons d'action.
Exigences d'attribution visuelle
Important : Vous devez indiquer clairement aux utilisateurs finaux quand un bouton d'action personnalisé partagera des informations utilisateur avec un tiers autre que Google. Consultez les exigences concernant l'attribution visuelle.
L'exemple de droite montre une image personnalisée qui indique clairement que les informations utilisateur seront envoyées à "Altostrat".
Appliquer des options de recherche et de filtrage
Utilisez les classes SearchMediaOptions et SearchReviewsOptions de AdvancedPlaceDetailsFragment ou AdvancedPlaceDetailsCompactFragment pour activer la recherche et le filtrage des contenus multimédias ou des avis.
Si vous utilisez les fonctions @Composable, utilisez com.google.android.libraries.places.compose.search.SearchMediaOptions pour activer la recherche et le filtrage des contenus multimédias, et com.google.android.libraries.places.compose.search.SearchReviewsOptions pour activer la recherche et le filtrage des avis.
Créer des emplacements de contenu personnalisés
Les emplacements de contenu personnalisés vous permettent d'ajouter votre propre contenu (comme des résumés générés par l'IA, des codes temporels d'itinéraire ou des badges personnalisés) directement dans des zones de mise en page prédéfinies.
Exigences d'attribution et suggestions de contenu pour les emplacements de contenu
Lorsqu'un emplacement de contenu personnalisé est installé, la mention est automatiquement mise à jour pour indiquer quel contenu est fourni par Google et quel contenu est fourni par des tiers.
À faire
Maintenez une hiérarchie visuelle claire entre les détails Google Places et le contenu personnalisé pour éviter toute ambiguïté sur la source des informations.
À faire
Envisagez de proposer des insights localisés et à forte valeur ajoutée, adaptés aux objectifs immédiats de vos utilisateurs. Des contenus personnalisés, tels que des fenêtres de réservation en temps réel ou la disponibilité actuelle, aident les utilisateurs à prendre des décisions plus rapides et plus éclairées.
À éviter
Ne dupliquez pas les détails des lieux Google existants, tels que les notes, les avis ou les horaires d'ouverture, même si vous avez masqué le contenu fourni par Google. Cela peut prêter à confusion quant à la source du contenu et à sa provenance (Google ou un tiers).
À éviter
N'affichez pas d'affirmations ni de badges non attribués (par exemple, "Meilleure recommandation") qui pourraient être confondus avec des recommandations officielles de Google. Le contenu personnalisé doit explicitement attribuer sa source.
À éviter
N'incluez pas d'annonces, de textes marketing, de remises promotionnelles ni d'invites d'abonnement dans les conteneurs de lieux personnalisés.
Pour ajouter du contenu personnalisé, utilisez le composable AdvancedPlaceDetailsCompact. Utilisez basicSectionTop ou basicSectionBottom pour spécifier la position du contenu.
Exemples avancés de Place Details
Personnaliser les boutons d'action
Utilisez l'interface PlaceActionProvider pour contrôler les actions disponibles pour chaque lieu.
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 } }) } }
Ajouter des actions personnalisées et prédéfinies
Cet exemple ajoute un bouton d'activation permettant à un utilisateur d'ajouter un lieu à ses favoris ou de le supprimer.
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() }
Utiliser des boutons standards prédéfinis
Créez des boutons d'action qui effectuent des actions standards définies par 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 }
Filtrer les avis et les contenus multimédias
Cet exemple de code n'affiche que les contenus multimédias et les avis qui mentionnent "spaghetti" et "tasty".
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)
Utiliser un composable pour une mise en page verticale
L'exemple de code suivant montre comment utiliser la fonction composable pour une mise en page verticale d'une carte AdvancedPlaceDetailsCompact.
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) } ) }
L'exemple de code suivant montre comment utiliser la fonction composable pour une mise en page verticale d'une carte AdvancedPlaceDetails.
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.AdvancedPlaceDetails 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 SampleAdvancedPlaceDetailsCard( placeId: String, bookmarkIcon: Painter, onSavePlaceClicked: (Place) -> Unit ) { AdvancedPlaceDetails( // 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), 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) } ) }
Créer des emplacements de contenu
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." ) } } }