Компонент Advanced Place Details
Расширенная версия компонента Place Details предлагает те же функции, что и Places Details Essentials. Вы также можете настроить командные кнопки компонента и применить параметры поиска и фильтрации к показываемым отзывам и медиаконтенту.
Встроенная поддержка Jetpack Compose
Places UI Kit предоставляет функции Jetpack Compose @Composable для AdvancedPlaceDetailsCompact и AdvancedPlaceDetails. Эти composable-функции используют поднятое состояние, встроенную поддержку модификаторов и DSL слотов, нативные для Compose. Пример
Токены для агентных приложений
Токен визуализации агентских данных позволяет агентскому приложению бесплатно показывать элементы Places UI Kit для мест в ответе инструментов агентов Maps Experience (ранее – Maps Grounding Lite). Подробнее о токене визуализации данных агента…
Расширенная конфигурация Place Details
Чтобы получить доступ к продвинутым функциям, используйте AdvancedPlaceDetailsFragment, AdvancedPlaceDetailsCompactFragment, composable-функцию AdvancedPlaceDetails или composable-функцию AdvancedPlaceDetailsCompact.
Параметры показа контента
Вы можете указать, какой контент показывать, используя перечисления в AdvancedPlaceDetailsFragment. Вы можете настроить всю ту же информацию о местах, что и в Places Details Essentials. Если вы используете composable-функции, то можете выбрать, будет ли показываться название места.
Настроить командные кнопки
Чтобы определить и настроить командные кнопки, используйте интерфейс PlaceActionProvider в AdvancedPlaceDetailsFragment или AdvancedPlaceDetailsCompactFragment.
Если вы используете функции @Composable, настройте командные кнопки с помощью лямбда-выражений mainActions и cornerActions.
Требования к визуальному указанию авторства
Важно! Вы должны четко сообщить конечным пользователям, что при нажатии на кнопку настраиваемого действия их данные будут переданы третьей стороне, не связанной с Google. Подробнее о требованиях по указанию авторства…
В примере справа показано специальное изображение, из которого понятно, что информация о пользователе будет отправлена в Altostrat.
Как использовать поиск и фильтры
Чтобы включить поиск и фильтрацию медиаконтента или отзывов, используйте классы SearchMediaOptions и SearchReviewsOptions из AdvancedPlaceDetailsFragment или AdvancedPlaceDetailsCompactFragment.
Если вы используете функции @Composable, то для поиска и фильтрации медиаконтента используйте com.google.android.libraries.places.compose.search.SearchMediaOptions, а для поиска и фильтрации отзывов – com.google.android.libraries.places.compose.search.SearchReviewsOptions.
Как создавать собственные рекламные места
С помощью специальных рекламных мест вы можете добавлять собственный контент (например, сводки, созданные ИИ, временные метки маршрута или специальные значки) непосредственно в предопределенные зоны макета.
Требования по указанию авторства и рекомендации по контенту для рекламных мест
Когда встраивается рекламное место с пользовательским контентом, раскрытие информации автоматически обновляется, чтобы уточнить, какой контент предоставляется Google, а какой – третьими лицами.
Значки должны:
Поддерживайте четкую визуальную иерархию между информацией о местах Google и собственным контентом, чтобы не возникало сомнений в источнике информации.
Значки должны:
Предоставляйте пользователям локализованную и ценную информацию, которая поможет им достичь своих целей. Например, данные о доступности номеров в реальном времени помогут пользователям быстрее принять решение.
Чего не следует делать
Не дублируйте существующую информацию о местах в Google, такую как оценки, отзывы или часы работы, даже если вы скрыли контент, предоставленный Google. В противном случае пользователи могут запутаться в том, кто является источником контента – Google или третья сторона.
Чего не следует делать
Не показывайте заявления или значки без указания авторства (например, "Лучшая рекомендация!"), которые могут быть ошибочно приняты за официальные рекомендации Google. В пользовательском контенте должен быть явно указан источник.
Чего не следует делать
Не добавляйте в контейнеры рекламу, маркетинговые тексты, скидки и предложения оформить подписку.
Чтобы добавить собственный контент, используйте composable-функцию AdvancedPlaceDetailsCompact. Используйте basicSectionTop или basicSectionBottom, чтобы указать позицию контента.
Примеры расширенных сведений о месте
Как настроить командные кнопки
Используйте интерфейс PlaceActionProvider, чтобы управлять доступными действиями для каждого места.
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 } }) } }
Добавление собственных и стандартных действий
В этом примере добавляется переключатель, позволяющий пользователю добавить место в избранное или удалить его оттуда.
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() }
Используйте стандартные кнопки
Создавайте командные кнопки, которые выполняют стандартные действия, определенные 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 }
Фильтровать отзывы и медиаконтент
В этом примере кода показаны только медиафайлы и отзывы, в которых упоминаются слова "спагетти" и "вкусно".
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)
Использование composable-функции для вертикального макета
В примере кода ниже показано, как использовать composable-функцию для вертикального макета карточки 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) } ) }
В примере кода ниже показано, как использовать composable-функцию для вертикального макета карточки 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) } ) }
Как создать рекламные места
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." ) } } }