Komponente „Advanced Place Details“

Die erweiterte Version der Place Details-Komponente bietet dieselben Funktionen wie Place Details Essentials. Außerdem können Sie die Aktionsbuttons der Komponente konfigurieren und Such- und Filteroptionen auf die angezeigten Rezensionen und Medien anwenden.

Integrierte Jetpack Compose-Unterstützung

Das Places UI Kit bietet Jetpack Compose-@Composable-Funktionen für AdvancedPlaceDetailsCompact und AdvancedPlaceDetails. Diese Composables verwenden den hochgestuften Status, die integrierte Unterstützung für Modifikatoren und Compose-native Slot-DSLs. Beispiel ansehen

Tokens für agentische Anwendungen

Mit dem Token für die agentische Datenvisualisierung kann Ihre agentische App Elemente des Places UI Kit für die Orte in einer Antwort der Maps Experience Agent Tools (früher Maps Grounding Lite) ohne zusätzliche Kosten anzeigen. Weitere Informationen finden Sie unter Agentisches Token für die Datenvisualisierung.

Erweiterte Konfiguration von Place Details

Verwenden Sie die AdvancedPlaceDetailsFragment, die AdvancedPlaceDetailsCompactFragment, die AdvancedPlaceDetails-Komposition oder die AdvancedPlaceDetailsCompact-Komposition, um auf erweiterte Funktionen zuzugreifen.

Anzeigeoptionen für Inhalte

Mit den Enums in AdvancedPlaceDetailsFragment können Sie festlegen, welche Inhalte angezeigt werden sollen. Sie können alle Inhalte konfigurieren, die auch in Place Details Essentials verfügbar sind. Wenn Sie die zusammensetzbaren Funktionen verwenden, können Sie auch festlegen, ob der Ortsname angezeigt werden soll.

Aktionsschaltflächen konfigurieren

Verwenden Sie die Schnittstelle PlaceActionProvider von AdvancedPlaceDetailsFragment oder AdvancedPlaceDetailsCompactFragment, um Aktionsschaltflächen zu definieren und anzupassen.

Wenn Sie @Composable-Funktionen verwenden, konfigurieren Sie Aktionsbuttons mit den Lambdas mainActions und cornerActions.

Anforderungen an die visuelle Attribution

Kompakte Ansicht der Ortsdetails mit benutzerdefinierten Schaltflächen
Kompaktansicht der erweiterten Ortsdetails mit benutzerdefinierter Schaltfläche

Wichtig: Sie müssen Endnutzern gegenüber klar angeben, wenn über einen benutzerdefinierten Aktionsbutton Nutzerdaten an einen anderen Dritten als Google weitergegeben werden. Weitere Informationen finden Sie unter Anforderungen an den visuellen Urheberrechtshinweis.

Im Beispiel rechts ist ein benutzerdefiniertes Bild zu sehen, aus dem hervorgeht, dass Nutzerinformationen an „Altostrat“ gesendet werden.

Such- und Filteroptionen anwenden

Verwenden Sie die Klassen SearchMediaOptions und SearchReviewsOptions von AdvancedPlaceDetailsFragment oder AdvancedPlaceDetailsCompactFragment, um die Suche und Filterung nach Medien oder Rezensionen zu ermöglichen.

Wenn Sie @Composable-Funktionen verwenden, können Sie mit com.google.android.libraries.places.compose.search.SearchMediaOptions die Suche und Filterung für Medien und mit com.google.android.libraries.places.compose.search.SearchReviewsOptions die Suche und Filterung für Rezensionen aktivieren.

Benutzerdefinierte Anzeigenflächen erstellen

Optionen für die Platzierung benutzerdefinierter Anzeigenflächen

Mit benutzerdefinierten Inhaltsflächen können Sie eigene Inhalte (z. B. KI-generierte Zusammenfassungen, Zeitstempel für den Reiseplan oder benutzerdefinierte Badges) direkt in vordefinierte Layoutbereiche einfügen.

Anforderungen an Quellenangaben und Inhaltsvorschläge für Inhaltsflächen

Wenn ein benutzerdefinierter Inhaltsbereich eingebunden wird, wird die Offenlegung automatisch aktualisiert, um klarzustellen, welche Inhalte von Google und welche von Drittanbietern bereitgestellt werden.

Dos

Sorgen Sie für eine klare visuelle Hierarchie zwischen Google Place Details und benutzerdefinierten Inhalten, um Unklarheiten über die Quelle der Informationen zu vermeiden.

Unklarheiten über die Informationsquelle vermeiden

Dos

Bieten Sie lokalisierte, hochwertige Informationen, die auf die unmittelbaren Ziele Ihrer Nutzer zugeschnitten sind. Mit maßgeschneiderten Inhalten wie Echtzeit-Buchungsfenstern oder aktueller Verfügbarkeit können Nutzer schneller fundierte Entscheidungen treffen.

Wertvolle Statistiken bereitstellen

Nicht erlaubt

Duplizieren Sie keine vorhandenen Google-Ortsdetails wie Bewertungen, Rezensionen oder Öffnungszeiten, auch wenn Sie die von Google bereitgestellten Inhalte ausgeblendet haben. Andernfalls kann es zu Verwirrung bei den Nutzern hinsichtlich der Quelle der Inhalte kommen, also ob sie von Google oder einem Drittanbieter stammen.

Keine Duplikate vorhandener Google-Ortsdetails erstellen

Nicht erlaubt

Verwenden Sie keine Behauptungen oder Badges ohne Quellenangabe (z. B. „Top-Empfehlung!“), die fälschlicherweise als offizielle Empfehlungen von Google interpretiert werden könnten. Bei benutzerdefinierten Inhalten muss die Quelle explizit angegeben werden.

Keine Behauptungen oder Badges ohne Quellenangabe anzeigen

Nicht erlaubt

In benutzerdefinierten Ortscontainern dürfen keine Anzeigen, Marketingtexte, Werberabatte oder Aufforderungen zum Abonnieren enthalten sein.

Keine Anzeigen, Marketingtexte, Werberabatte oder Aufforderungen zum Abonnieren einfügen

Wenn Sie benutzerdefinierte Inhalte hinzufügen möchten, verwenden Sie die komponierbare Funktion AdvancedPlaceDetailsCompact. Verwenden Sie basicSectionTop oder basicSectionBottom, um die Position des Inhalts anzugeben.

Beispiele für erweiterte Ortsdetails

Aktionsschaltflächen anpassen

Über die PlaceActionProvider-Schnittstelle können Sie festlegen, welche Aktionen für die einzelnen Orte verfügbar sind.

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

Benutzerdefinierte und vordefinierte Aktionen hinzufügen

In diesem Beispiel wird ein Ein/Aus-Button hinzugefügt, mit dem ein Nutzer einen Ort als Favorit markieren oder die Markierung aufheben kann.

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()
}

Vordefinierte Standardschaltflächen verwenden

Aktionsbuttons erstellen, die von Google definierte Standardaktionen ausführen.

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
  }

Rezensionen und Medien filtern

In diesem Codebeispiel werden nur Medien und Rezensionen angezeigt, in denen „Spaghetti“ und „lecker“ erwähnt werden.

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 für ein vertikales Layout verwenden

Das folgende Codebeispiel zeigt, wie die zusammensetzbare Funktion für ein vertikales Layout für eine AdvancedPlaceDetailsCompact-Karte verwendet wird.

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

Das folgende Codebeispiel zeigt, wie die zusammensetzbare Funktion für ein vertikales Layout für eine AdvancedPlaceDetails-Karte verwendet wird.

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

Content-Slots erstellen

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