Advanced Place Details コンポーネント
Place Details コンポーネントの Advanced バージョンは、Place Details Essentials と同じ機能を備えています。また、コンポーネントの操作ボタンを設定したり、表示されるレビューやメディアに検索オプションやフィルタ オプションを適用したりすることもできます。
組み込みの Jetpack Compose サポート
Places UI キットには、AdvancedPlaceDetailsCompact と AdvancedPlaceDetails 用の Jetpack Compose @Composable 関数が用意されています。これらのコンポーザブルは、ホイスティングされた状態、組み込みの修飾子のサポート、Compose ネイティブのスロット DSL を使用します。例をご覧ください。
エージェント アプリのトークン
エージェント型データ可視化トークンを使用すると、エージェント型アプリは、Maps Experience Agent Tools(旧称 Maps Grounding Lite)のレスポンスに含まれる場所の Places UI キット 要素を追加料金なしで表示できます。詳細については、エージェント データ可視化トークンをご覧ください。
Place Details の高度な設定
高度な機能にアクセスするには、AdvancedPlaceDetailsFragment、AdvancedPlaceDetailsCompactFragment、AdvancedPlaceDetails コンポーザブル、または AdvancedPlaceDetailsCompact コンポーザブルを使用します。
コンテンツの表示オプション
表示するコンテンツは、AdvancedPlaceDetailsFragment の列挙型を使用して指定できます。Place Details Essentials と同じコンテンツをすべて構成できます。コンポーズ可能な関数を使用している場合は、場所の名前を表示するかどうかを選択することもできます。
操作ボタンを設定する
AdvancedPlaceDetailsFragment または AdvancedPlaceDetailsCompactFragment の PlaceActionProvider インターフェースを使用して、操作ボタンを定義、カスタマイズします。
@Composable 関数を使用している場合は、mainActions と cornerActions ラムダを使用して操作ボタンを構成します。
視覚的な帰属表示の要件
重要: カスタム アクション ボタンによってユーザー情報が Google 以外の第三者と共有される場合は、その旨をエンドユーザーに明示する必要があります。視覚的な帰属表示の要件をご覧ください。
右の例は、ユーザー情報が「Altostrat」に送信されることを明確に示すカスタム画像です。
検索とフィルタリングのオプションを適用する
AdvancedPlaceDetailsFragment または AdvancedPlaceDetailsCompactFragment の SearchMediaOptions クラスと SearchReviewsOptions クラスを使用して、メディアまたはレビューの検索とフィルタリングを有効にします。
@Composable 関数を使用している場合は、com.google.android.libraries.places.compose.search.SearchMediaOptions を使用してメディアの検索とフィルタリングを有効にし、com.google.android.libraries.places.compose.search.SearchReviewsOptions を使用してレビューの検索とフィルタリングを有効にします。
カスタム コンテンツ スロットを作成する
カスタム コンテンツ スロットを使用すると、事前定義されたレイアウト ゾーンに独自のコンテンツ(AI 生成の概要、旅程のタイムスタンプ、カスタムバッジなど)を直接追加できます。
コンテンツ スロットの帰属表示の要件とコンテンツの提案
カスタム コンテンツ スロットがマウントされると、開示情報が自動的に更新され、Google が提供するコンテンツと、サードパーティが提供するコンテンツが明確に示されます。
すべきこと
Google Place Details とカスタム コンテンツの間に明確な視覚的階層を維持し、情報のソースがあいまいにならないようにします。
すべきこと
ユーザーの当面の目標に合わせた、ローカライズされた価値の高い分析情報を検討します。リアルタイムの予約可能期間や現在の空き状況など、カスタマイズされたコンテンツは、ユーザーがより迅速かつ十分な情報に基づいて意思決定を行うのに役立ちます。
禁止事項
Google が提供するコンテンツを非表示にしている場合でも、評価、クチコミ、営業時間など、既存の Google Place Details を複製しないでください。そうすると、コンテンツの提供元が Google なのかサードパーティなのか、ユーザーが混乱する可能性があります。
禁止事項
Google の公式な推奨と誤解される可能性がある、帰属表示のない主張やバッジ(「おすすめ!」など)を表示しないでください。カスタム コンテンツでは、そのソースを明示的に示す必要があります。
禁止事項
カスタム プレイス コンテナ内に広告、マーケティング コピー、プロモーション割引、定期購入のプロンプトを含めないでください。
カスタム コンテンツを追加するには、AdvancedPlaceDetailsCompact コンポーザブルを使用します。basicSectionTop または basicSectionBottom を使用して、コンテンツの位置を指定します。
Place Details(Advanced)の例
アクション ボタンをカスタマイズする
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 }
クチコミとメディアをフィルタ
このコードサンプルは、「spaghetti」と「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)
縦向きレイアウトにコンポーザブルを使用する
次のコードサンプルは、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) } ) }
次のコードサンプルは、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." ) } } }