Widget de embasamento do Maps

Este produto ou recurso é experimental (pré-GA). Os produtos e recursos pré-GA têm suporte limitado, e é possível que as mudanças neles não sejam compatíveis com versões anteriores. As Soluções pré-GA são cobertas pelos Termos de Serviço da Plataforma Google Maps. Para mais detalhes, consulte as descrições da fase de lançamento.

O widget contextual é uma oferta de pré-GA do Google Maps, um contêiner visual usado para apoiar ou complementar outros conteúdos do Google Maps. Com o widget contextual do Google Maps, você pode integrar o embasamento com o Google Maps aos seus aplicativos para criar uma experiência de chat conversacional com tecnologia de LLM. O widget contextual é renderizado usando o token de contexto, googleMapsWidgetContextToken, que é retornado na resposta da API Vertex AI e pode ser usado para renderizar conteúdo visual.

O widget contextual tem funções diferentes dependendo do seu cenário:

• Ele mostra conteúdo gerado pelo usuário (UGC) subjetivo no cenário em que o Google Maps usa solicitações para gerar respostas.
• Ele ajuda a enriquecer os resultados com visualizações de mapa e dados quando a Vertex AI gera apenas uma resposta de texto.

Como o widget contextual funciona

O widget contextual mostra uma resposta do recurso de embasamento com o Google Maps na Vertex AI, na forma de um googleMapsWidgetContextToken. Use esse token para renderizar o widget contextual e mostrar a resposta. Saiba mais. O fluxo de eventos é o seguinte:

1. Chame a API Vertex AI com uma consulta embasada no Google Maps.
2. A Vertex AI retorna um googleMapsWidgetContextToken.
3. Renderize o widget contextual usando o token.
4. O widget contextual mostra a resposta da Vertex AI.

O exemplo a seguir mostra como um token de contexto aparece quando retornado da API Vertex AI.

"googleMapsWidgetContextToken": "widgetcontent/AcBXPQdpWQWbap9H-OH8sEKmOXxmEKAYvff0tvthhneMQC3VrqWCjpnPBl4-Id98FGiA_S_t8aeAeJj0T6JkWFX56Bil8oBSR0W8JH3C_RSYLbTjxKdpxc9yNn6JcZTtolIRZon9xi6WpNGuSyjcIxWu2S0hwpasNOpUlWrG1RxVCB4WD1fsz_pwR236mG36lMxevXTQ_JnfdYNuQwQ4Lc3vn...<snip>...
Ts5VJE_b3IC5eE_6wez0nh61r7foTUZpP7BXMwxR-7Wyfcj6x1v6mIWsFGr1o0p_HSAMNqWPg-aFVnkPLhAkOR6MaNZOfezTva-gxHlu7z_haFvYxcUE1qfNVQ",

Renderizar o widget contextual do Google Maps

Para renderizar e usar o widget contextual do Google Maps, use a versão Alfa da API Maps JavaScript na página que mostra o widget. Para mais informações, consulte Carregar a API Maps JavaScript. Você também precisa usar a chave de API ativada para carregar a API Maps JavaScript. Verifique se a biblioteca places foi carregada.

A seção a seguir descreve como renderizar o widget contextual do Google Maps. Crie um widget contextual usando HTML personalizado ou JavaScript.

Usar elementos HTML personalizados

A seção a seguir descreve como renderizar o widget contextual do Google Maps usando elementos HTML personalizados. Crie um widget contextual adicionando o elemento gmp-place-contextual à página.

1. Adicione o elemento gmp-place-contextual à página:

   <gmp-place-contextual id="widget"></gmp-place-contextual>

2. Em qualquer resposta baseada no Google Maps, há um googleMapsWidgetContextToken correspondente que pode ser usado para renderizar o widget contextual. A função a seguir mostra como atualizar o token de contexto:

   let widget = document.querySelector('#widget'); // a div that contains the widget
   widget.contextToken = contextToken;

3. Opcional: especifique o layout da lista. Os valores válidos incluem:
   • Layout compacto: <gmp-place-contextual-list-config layout="compact">
   • Layout vertical: <gmp-place-contextual-list-config layout="vertical">

   O exemplo a seguir mostra como mudar o layout da lista para compacto:

   <gmp-place-contextual id="widget">
     <gmp-place-contextual-list-config layout="compact">
     </gmp-place-contextual-list-config>
   </gmp-place-contextual>

4. Opcional: mude o modo do mapa. Os valores válidos incluem:
   • Mapa de roteiro 2D: <gmp-place-contextual-map-config map-mode="roadmap">
   • Mapa híbrido 3D: <gmp-place-contextual-map-config map-mode="hybrid">
   • Nenhum mapa: <gmp-place-contextual-map-config map-mode="none">
O exemplo a seguir mostra como mudar o modo do mapa para um mapa 2D:

<gmp-place-contextual id="widget">
  <gmp-place-contextual-map-config map-mode="roadmap">
  </gmp-place-contextual-map-config>
</gmp-place-contextual>

Usar JavaScript

A seção a seguir descreve como renderizar o widget contextual do Google Maps criando um PlaceContextualElement de forma programática e anexando-o ao DOM.

1. Crie um widget contextual.

   let widget = document.querySelector('#widget');  // a div that contains the widget
   
   async function createWidget(contextToken) {
     await google.maps.importLibrary('places');
     const placeContextualElement = new
         google.maps.places.PlaceContextualElement({ contextToken }); // contextToken can be empty at initialization.
     widget.appendChild(placeContextualElement);
   }

2. Em qualquer resposta baseada no Google Maps, há um googleMapsWidgetContextToken correspondente usado para renderizar o widget contextual. A função a seguir mostra como atualizar o token de contexto:

   widget.contextToken = contextToken;

3. Opcional: especifique o layout da lista. Os valores válidos incluem:
   • Layout compacto: google.maps.places.PlaceContextualListLayout.COMPACT
   • Layout vertical: google.maps.places.PlaceContextualListLayout.VERTICAL

O exemplo a seguir mostra como mudar o layout da lista para compacto:

const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
  layout: google.maps.places.PlaceContextualListLayout.COMPACT
});
widget.appendChild(widgetConfig);

4. Opcional: mude o modo do mapa. Os valores válidos incluem:
   • Mapa de roteiro 2D: google.maps.places.PlaceContextualListMapMode.ROADMAP
   • Mapa híbrido 3D: google.maps.places.PlaceContextualListMapMode.HYBRID
   • Nenhum mapa: google.maps.places.PlaceContextualListMapMode.NONE

O exemplo a seguir mostra como mudar o modo do mapa para um mapa 2D:

const widgetConfig = new google.maps.places.PlaceContextualListConfigElement({
  mapMode: google.maps.places.PlaceContextualListMapMode.ROADMAP
});
widget.appendChild(widgetConfig);

Territórios proibidos

O Google Maps restringe determinados conteúdos e atividades para manter uma plataforma segura e confiável. Para conferir uma lista de territórios proibidos, consulte Territórios proibidos da Plataforma Google Maps.