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 ラムダを使用して操作ボタンを構成します。

視覚的な帰属表示の要件

Place Details のコンパクト ビュー (カスタマイズ可能なボタン付き)
カスタマイズされたボタンを含む、高度な Place Details のコンパクト ビュー

重要: カスタム アクション ボタンによってユーザー情報が 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 Place Details を複製しない

禁止事項

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."
            )
        }
    }
}