Guia do programador de agentes de comércio conversacional

Este guia detalha como fazer a integração com a API Conversacional para oferecer experiências de chat dinâmicas com tecnologia de IA aos seus clientes. Ao compreender os diferentes tipos de consultas e tirar partido das respostas da API, pode fornecer pesquisas de produtos relevantes, responder às perguntas dos clientes e orientar os utilizadores finais ao longo do respetivo percurso de compras.

O elemento conversationalFilteringMode na API Conversacional esclarece as diferenças entre o agente de comércio conversacional e a filtragem de produtos conversacional.

Configuração

A API Conversational suporta a funcionalidade de agente de comércio conversacional:

• gRPC: conversationalSearchService
• RESTO: conversationalSearch

A API Conversacional permite uma experiência de chat em que os seus utilizadores enviam consultas e o sistema devolve uma resposta de texto, tipos de consultas classificados e potenciais opções de pesquisa refinadas.

Esta API funciona como um serviço de streaming, o que permite a deteção antecipada da intenção da consulta. As interações subsequentes na conversa requerem a anexação de um conversation_id.

Para devolver resultados da pesquisa, a API Retail antiga tem de ser chamada em paralelo com a API Conversational.

Envie uma consulta do utilizador final

Esta secção descreve como iniciar uma experiência de agente de comércio conversacional. Por exemplo, o utilizador pode introduzir Ajuda-me a planear uma festa no campo de pesquisa.

Envie um pedido para o Vertex AI Search for commerce

Existem dois pontos finais da API diferentes:

1. A API Conversacional tem de ser usada para obter a experiência conversacional.
2. A API Search principal tem de ser usada para obter resultados da pesquisa.

Ponto final 1: pedido de API de conversação

• Deve criar um pedido de agente de comércio conversacional definindo a entrada do utilizador como a consulta.
• O pedido deve ser enviado como um pedido HTTP POST para o ponto final projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Método HTTP e ponto final

  POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
  

Pedido de API de conversação:

Consulta inicial

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your core Search API calls to ensure consistency between LLM answers and search results.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
    // Example: "userId": "user123", "userAgent": "Chrome/120.0"
  },
  "conversationalFilteringSpec": {
    // Optional: Controls conversational filtering behavior. Defaults to DISABLED if unset.
    // "conversational_filtering_mode": "DISABLED" - Otherwise you can also explicitly set to disabled.
}

• placement: o nome do recurso do posicionamento (como projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Este é um parâmetro de caminho e é obrigatório.
• query: a consulta de pesquisa não processada do utilizador. Este campo é obrigatório.
• branch: o nome do recurso da ramificação, como projects/P/locations/L/catalogs/C/branches/B. Se não for definido, é usado default_branch. Este campo é obrigatório.
• visitorId: um identificador exclusivo para acompanhar os visitantes. Este campo é obrigatório.
• conversationId: um ID exclusivo para acompanhar as sessões de conversa. Para o pedido inicial numa nova conversa, este campo deve estar vazio. Para pedidos subsequentes na mesma conversa, tem de ser definido como o conversation_id recebido no ConversationalSearchResponse anterior.
• searchParams: (Opcional) Parâmetros de pesquisa principais padrão, como filter, canonicalFilter, sortBy e boostSpec. É fundamental que estes parâmetros reflitam a configuração usada nas chamadas API Search principais para garantir a consistência entre as respostas do MDG e os resultados da pesquisa de produtos apresentados.
• userInfo: (Opcional) Informações do utilizador para uma personalização melhorada. Pode incluir userId, user_agent e direct_user_request (booleano).
• conversationalFilteringSpec: (Opcional) Especifica o modo de filtragem conversacional. Se não estiver definido, a predefinição é DISABLED.

  mode: integre a API Conversational através de um destes três modos para controlar a filtragem de produtos conversacional:

• DISABLED: neste modo, o cliente implementa apenas a pesquisa de agentes de comércio conversacional. Este é o modo preferencial para este guia de implementação na pesquisa de agentes de comércio conversacional.

Exemplo de pedido de API

        placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: DISABLED
        }
      

Exemplo de resposta da API

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
      

• ENABLED: neste modo, o cliente implementa todas as capacidades de conversa, o que inclui a pesquisa de agentes de comércio conversacional e a filtragem conversacional de produtos.

Consulte o guia adicional sobre como integrar ambos os produtos de conversa.

Exemplo de pedido de API

        placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search"
        branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch"
        query: "show me some monster energy drinks"
        visitor_id: "test"
        conversational_filtering_spec {
          conversational_filtering_mode: ENABLED
        }
      

Exemplo de resposta da API

        user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
        conversational_filtering_result: {
            followup_question{
              followup_question: "What is the size?"
              suggested_answers {
                product_attribute_value {
                  name: "size",
                  value: "12oz"
                }
              }
        }
        }
      

• CONVERSATIONAL_FILTER_ONLY: se for escolhido, o cliente só implementa a filtragem de produtos conversacional. Com este modo selecionado, o utilizador só tem acesso à filtragem de produtos conversacional, sem gerar uma resposta do MDG, uma classificação de consultas nem consultas de pesquisa sugeridas.

Consulte o guia do programador de filtros de produtos conversacionais para mais informações.

Ponto final 2: pedido da API Core Search

Existem duas abordagens principais para apresentar resultados da pesquisa na sua interface Web.

Opção 1: mostrar sempre os resultados da pesquisa

Se o design da experiência do utilizador determinar que os resultados da pesquisa devem ser sempre apresentados, independentemente do resultado da conversa, como numa área de resultados da pesquisa dedicada junto ao chat, envie a consulta original do utilizador para a API Product Search principal com a sua chamada para a API Conversational. Isto ajuda a garantir que as fichas de produtos estão imediatamente disponíveis.

Opção 2: mostrar resultados da pesquisa com base na saída conversacional

Se o design da experiência do utilizador for mais dinâmico e quiser apresentar resultados da pesquisa apenas consoante a resposta da API Conversacional, como apenas para consultas SIMPLE_PRODUCT_SEARCH ou sempre que forem fornecidas sugestões refined_search, aguarde a resposta da API Conversacional antes de enviar quaisquer consultas para a API Google Product Search principal. Se houver uma resposta, use a consulta refined_search fornecida para obter resultados de produtos.

Independentemente da opção de interface do utilizador que escolher, quando precisar de obter resultados reais de produtos, pode fazer uma chamada à API Retail. Para mais informações, consulte o artigo Compreenda os tipos de consultas e as ações do retalhista.

Método HTTP e ponto final

    POST https://retail.googleapis.com/v2beta/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:search
    

Pedido de API de pesquisa do produto principal:

Consulta inicial

    {
      "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search",
        // Or if using legacy placements:
        // "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
      "query": "Help me plan a party", // This is the original user query
      "visitorId": "your_visitor_id",
      "branch": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch",
      "pageSize": 20, // Optional: Number of results to return per page
      "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")", // Mirroring the filter from the Conversational Commerce API
      "orderBy": "relevance DESC", // Optional
      "userInfo": {
        // Optional: User information for enhanced personalization, should mirror Conversational Commerce API
        // "userId": "user123", "userAgent": "Chrome/120.0"
      },
      "searchMode": "PRODUCT_SEARCH" // Typically for product searches
    }
    

• placement (Obrigatório): o nome do recurso da configuração de publicação da pesquisa de retalho ou do posicionamento antigo. Exemplo: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
• query: obrigatório. A consulta de pesquisa. Pode ser a entrada não processada do utilizador, como Ajuda-me a planear uma festa, ou uma entrada mais otimizada refinedSearch.query (como artigos de planeamento de festas, decorações) obtida a partir da resposta da API Conversational Commerce.
• visitorId: obrigatório. Um identificador exclusivo para acompanhar os visitantes. Isto deve ser consistente com o visitorId enviado para a API Conversational Commerce para o mesmo utilizador final.
• branch (Obrigatório): o nome do recurso da ramificação, como projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
• pageSize (Opcional): o número máximo de produtos a devolver.
• filter (Opcional): usado para filtrar os resultados da pesquisa. É aqui que aplicaria todos os filtros que refletem o que envia em `searchParams` para a API Conversational Commerce para garantir a consistência.
• orderBy (Opcional): especifica a ordem pela qual os produtos são devolvidos (por exemplo, por relevância ou por preço).
• userInfo (Opcional): informações do utilizador para personalização, que devem ser consistentes com a chamada da API Conversational Commerce.
• searchMode (Opcional): define o comportamento de pesquisa. PRODUCT_SEARCH é comum para consultas gerais de produtos.

Compreenda a resposta

Este exemplo de código demonstra uma resposta da API Conversational commerce.

A resposta da API (ConversationalSearchResponse) inclui query_types, conversational_text_response (se aplicável), opções refined_search e, potencialmente, um followup_question ou um conversational_filtering_result. O conversation_id é essencial para continuar a sessão.

Resposta do Vertex AI Search for commerce

Este exemplo de código demonstra uma resposta da API Conversacional:

Resposta inicial

    {
      "userQueryTypes": ["INTENT_REFINEMENT"],
      "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
      "followupQuestion": {
        "followupQuestion": "What kind of party are you planning?"
      },
      "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
      "refinedSearch": [
        { "query": "Decorations" },
        { "query": "Snacks" },
        { "query": "Party Supplies" },
        { "query": "Drinks" },
        { "query": "Cake" }
      ],
      "state": "SUCCEEDED"
    }
    

O que os retalhistas devem fazer com a resposta (geral)

Renderize estes campos a partir da resposta:

• user_query_types: este campo fornece as classificações da intenção do utilizador. Para ver ações detalhadas com base nestes tipos, consulte o artigo Compreenda os tipos de consultas e as ações do retalhista.
• conversation_id: pode armazenar este ID exclusivo no armazenamento de sessão do navegador ou num armazenamento do lado do cliente semelhante para manter a sessão de conversa com o servidor. Isto é fundamental para distinguir entre várias conversas em curso para um único comprador. O seu modelo retém o contexto para um determinado conversation_id. O envio de um novo conversation_id inicia uma nova sessão. Recomendamos que defina a duração da sessão, como 30 minutos de inatividade.
• refined_search: esta é uma lista de consultas de pesquisa refinadas propostas usadas para obter os resultados da pesquisa relevantes. Para o SIMPLE_PRODUCT_SEARCH, é sempre uma única consulta. Para outras consultas que procuram respostas de MDIs, é uma ou mais. As consultas refined_search podem ser usadas para chamadas à API Search principal (SearchService.Search) ou também podem ser apresentadas ao seu utilizador como sugestões.
• conversational_text_response: apresente este texto ao utilizador como a resposta principal gerada pela IA à respetiva consulta.
• followup_question: opcional. É apresentado o followup_question.
• state: este campo indica o estado da geração de respostas ("STREAMING" ou "SUCCEEDED"). Pode usá-lo para feedback da experiência do utilizador, como mostrar um indicador de carregamento até "SUCCEEDED". Mais detalhes sobre este assunto na secção seguinte.

Compreenda a API de streaming

A API Conversational commerce funciona como uma API de streaming. Isto significa que o utilizador recebe partes da resposta em vários blocos, em vez de uma única carga útil completa.

O primeiro bloco da resposta inclui as consultas query_types e refined_search, e o respetivo state é indicado como STREAMING. Esta deteção precoce da intenção e disponibilidade imediata de refinamentos de pesquisa permite que o seu modelo tome decisões rápidas sobre como processar a consulta do utilizador e como gerir a experiência do utilizador relativamente à latência das respostas do MDIs:

• Para tipos de consultas que não esperam uma resposta de texto conversacional, como SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT:
• Uma vez que query_types estão no primeiro bloco, o sistema sabe imediatamente que não vai receber uma resposta do MDI/CE. Pode continuar com o processamento predefinido para estes tipos, como apresentar uma mensagem estática ou redirecionar para o apoio técnico, sem aguardar mais resultados da conversa.
• Especificamente para SIMPLE_PRODUCT_SEARCH, o seu sistema pode fazer imediatamente uma chamada direta para a API Search principal através da consulta refined_search recebida no primeiro fragmento. Isto ajuda a garantir que os resultados da pesquisa são apresentados com um atraso mínimo, cumprindo os SLAs típicos da experiência de pesquisa.
• Para tipos de consultas que esperam uma resposta de texto conversacional, como INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT:
• Recebe as consultas query_types e refined_search no bloco inicial. Pode iniciar imediatamente uma chamada paralela à API Google Search Core usando estas consultas refined_search para começar a carregar os resultados dos produtos.
• Os fragmentos subsequentes são transmitidos em fluxo contínuo, contendo diferentes secções da resposta de texto conversacional. Durante este período, o state permanece "STREAMING".
• Por último, o último fragmento inclui a resposta de texto conversacional completa e o respetivo state é alterado para "COMPLETED".
• Esta abordagem de streaming permite uma experiência do utilizador final fluida, em que os resultados da pesquisa podem começar a ser carregados enquanto o resumo de IA está a ser gerado. Pode optar por apresentar um indicador de carregamento para a resposta conversacional ou apresentar a resposta conversacional depois de ser totalmente transmitida.

Compreenda os tipos de consultas e as ações do retalhista

O campo query_types na resposta é uma lista que indica as classificações da intenção do utilizador. O seu sistema deve processar estes elementos da seguinte forma. Tenha em atenção que conversational_text_response se refere à resposta de linguagem natural gerada pela IA da API.

O agente de comércio conversacional usa categorias de consultas de pesquisa para determinar se é gerada uma resposta baseada em MDIs e como as consultas dos utilizadores finais são processadas pelas APIs Conversacionais e de Pesquisa nestes cenários:

Categorias	Classificações de consultas
1.º Consultas irrelevantes que não requerem uma resposta do MDG	QUERY_TYPE_UNSPECIFIED: tipo de consulta não especificado. RETAIL_IRRELEVANT: consultas irrelevantes para o domínio de retalho, por exemplo, uma consulta adversária (como como fazer uma bomba),uma consulta conversacional (como como está) ou uma consulta de jailbreak (como escrever um poema). BLOCKLISTED: Consultas explicitamente bloqueadas pelos clientes de comércio (como Quais são os efeitos secundários do Advil?).
2.º Consultas de apoio técnico e informações	ORDER_SUPPORT: consulta auxiliar ou de apoio técnico (como Acompanhar a minha encomenda, estado da encomenda 12345). DEALS_AND_COUPONS: consultas relevantes para ofertas, promoções, ofertas de produtos e descontos (como Existem ofertas para o Dia de Ação de Graças?). STORE_RELEVANT: consultas relevantes para localizações de lojas, incluindo o horário de funcionamento e a disponibilidade de stock de produtos (como Temos leite em stock?). RETAIL_SUPPORT: consultas relevantes para compras, incluindo métodos de pagamento (Que métodos de pagamento aceitam?).
3.º Pesquisas de palavras-chave que não requerem um MDG Pedido de API conversacional: Consulta inicial { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "show me some monster energy drinks", "visitorId": "test" } Resposta da API de conversação: Resposta inicial { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } Pedido da API Search: Consulta de seguimento { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	SIMPLE_PRODUCT_SEARCH: pesquisa básica de produtos, como vestido vermelho ou mostra algumas bebidas Monster.
4.º Consultas de procura de respostas de MDI/CE Pedido de API conversacional: Consulta inicial { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "Compare 1% milk with 2% milk", "visitorId": "test" } Resposta da API de conversação: Resposta inicial { "userQueryTypes": ["PRODUCT_COMPARISON"], "conversationalTextResponse": "1% milk contains 110 calories, 1.5 g of saturated fat, and 140 mg of sodium per cup. 2% milk is reduced fat with 37% less fat than regular milk and contains vitamins A & D.", "conversationId": "0e1cfdac-802f-422d-906e-9fc9f9d733ba", "refinedSearch": [ { "query": "1% milk" }, { "query": "2% milk" } ] } Pedido da API Search: Consulta de seguimento { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "1% milk", "visitorId": "test" }	PRODUCT_DETAILS: o utilizador está à procura de detalhes e especificações do produto, como mostra-me as especificações de [nome do produto], qual é o teor de proteína do leite com 2% de gordura?. PRODUCT_COMPARISON: comparação de produtos, como compare [product name] and [product name], Compare 1% milk with 2% milk. BEST_PRODUCT: consultas com o padrão mais correspondente, como Qual é o cookie mais saudável? Qual é a melhor marca de leite?
5.º Refinamento de intenções Pedido de API conversacional: Consulta inicial { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "branch": "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch", "query": "Help me plan a party", "visitorId": "test" } Resposta da API de conversação: Resposta inicial { "userQueryTypes": ["INTENT_REFINEMENT"], "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.", "followupQuestion": { "followupQuestion": "What kind of party are you planning?" }, "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", "refinedSearch": [ { "query": "Decorations" }, { "query": "Snacks" }, { "query": "Party Supplies" }, { "query": "Drinks" }, { "query": "Cake" } ], "state": "SUCCEEDED" }	INTENT_REFINEMENT: O tipo não é claro e pode ser necessária uma conversa de seguimento ou um refinamento para esclarecer o tipo, como Ajuda-me a planear uma festa. Esta é, muitas vezes, a intenção mais popular nas conversas.

Categoria 1. Consultas irrelevantes que não requerem uma resposta de um MDG

• QUERY_TYPE_UNSPECIFIED:
• Não é fornecido nenhum conversational_text_response.
• Ação: processe como um caso predefinido ou de erro. Pode pedir ao utilizador esclarecimentos ou direcioná-lo para onde pode receber ajuda geral.
• RETAIL_IRRELEVANT:
• Não é fornecido nenhum conversational_text_response.
• Ação: resolva esta situação apresentando uma mensagem adequada, como Não consigo responder a essa pergunta ou Sou um assistente de compras. Como posso ajudar?, conforme definido pelo design da sua aplicação.
• BLOCKLISTED:
• Não é fornecido nenhum conversational_text_response.
• Ação: processe de acordo com a sua política de lista de bloqueio, normalmente mostrando uma mensagem genérica não é possível satisfazer este pedido.

Categoria 2. Consultas de apoio técnico e informações

Para estes tipos, a API não fornece um conversational_text_response direto por predefinição, mas tem opções para direcionar para os links ou os recursos certos.

• ORDER_SUPPORT:
• Ação predefinida: não é fornecido nenhum conversational_text_response. A sua interface Web tem de apresentar alguma mensagem padrão, links relevantes ou redirecionar a consulta para a sua própria API de apoio técnico dedicada ou canal de serviço ao cliente.
• DEALS_AND_COUPONS:
• Ação predefinida: não é fornecido nenhum conversational_text_response. A sua interface Web tem de apresentar alguma mensagem padrão, links relevantes ou redirecionar a consulta para o seu sistema de promoções ou ofertas.
• STORE_RELEVANT:
• Ação predefinida: não é fornecido nenhum conversational_text_response. A sua interface Web tem de apresentar alguma mensagem padrão, links relevantes ou redirecionar a consulta para o seu próprio localizador de lojas ou sistema de informações.
• RETAIL_SUPPORT:
• Ação predefinida: não é fornecido nenhum conversational_text_response. A sua interface Web tem de apresentar alguma mensagem padrão, links relevantes ou redirecionar a consulta para o seu próprio sistema de informações e perguntas frequentes.

Categoria 3. Pesquisas por palavras-chave que não requerem respostas de MDIs

• SIMPLE_PRODUCT_SEARCH:
• Não é gerada nenhuma resposta de texto conversacional.
• Ação: a resposta da API devolve sempre uma única consulta refined_search. Esta consulta refinada funciona como um termo de pesquisa sugerido. Faça uma chamada direta à API Search principal (SearchService.Search) e obtenha resultados de produtos relevantes com a consulta original ou a consulta refined_search. A refined_search.query pode não ser diretamente da entrada do utilizador final atual, mas também pode ser derivada do contexto do histórico do chat. Por exemplo, se um utilizador final tiver refinado anteriormente vestido de festa para vermelhos, a consulta refinada pode tornar-se vestido de festa vermelho.
• Para interfaces conversacionais (como chatbots): é altamente recomendável usar o refined_search.query fornecido pela API. Num fluxo de conversa, as consultas em linguagem natural, como "podes ajudar-me a encontrar bananas", são automaticamente otimizadas pela API para um termo de pesquisa de produto preciso ("bananas"), o que leva a resultados de produtos mais relevantes.
• Para experiências de pesquisa essenciais (como a página de resultados da pesquisa): tem a flexibilidade de usar o refined_search.query da API ou a consulta original fornecida pelo utilizador final, porque é mais provável que a consulta original já seja um termo de pesquisa de produtos preciso. Escolha a opção que melhor se adequa à sua interface Web e estratégia de apresentação dos resultados da pesquisa.
• Opções de experiência do utilizador: a conversa não tem de terminar para SIMPLE_PRODUCT_SEARCH consultas. O utilizador pode continuar a conversa transmitindo o conversation_id em pedidos subsequentes.
• Opção A: terminar a interface Web conversacional: muitos retalhistas optam por fazer a transição do utilizador para uma página de resultados da pesquisa padrão assim que é detetado um SIMPLE_PRODUCT_SEARCH, fechando efetivamente a janela de chat. Neste cenário, se o utilizador final introduzir uma nova consulta na caixa de pesquisa padrão sem o conversation_id anterior, é tratada como uma conversa nova e separada, e é emitido um novo conversation_id.
• Opção B: continuar com a interface Web de conversação: os retalhistas podem optar por manter a janela de chat aberta. Isto permite que o utilizador regresse a um modo de conversação. A decisão de implementar a opção A ou B depende inteiramente da experiência do utilizador preferida do retalhista.

Para atribuir com precisão as consultas de pesquisa a interações conversacionais e usar as capacidades de análise completas na Vertex AI Search for commerce, a etiquetagem de eventos adequada é crucial:

1. Recuperar conversation_id. Quando faz uma chamada API conversationalSearch, é devolvido o ConversationalSearchResponse.conversation_id.
2. Etiquete eventos de utilizadores. Nos casos em que a resposta conversacional leva a uma consulta de pesquisa, como se o seu sistema executar automaticamente uma pesquisa com base na consulta refinada para SIMPLE_PRODUCT_SEARCH, tem de etiquetar esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao etiquetar corretamente UserEvent.conversation_id, a sua análise pode atribuir com precisão as consultas de pesquisa às interações de conversa anteriores, o que fornece estatísticas valiosas sobre o comportamento e os caminhos de conversão do utilizador.

Categoria 4. Consultas que procuram respostas de MDIs/CEs

Para estes tipos de consultas, a API gera uma conversational_text_response (resposta do MDI/CE) e também pode fornecer uma ou mais consultas refined_search. A conversa não termina e o utilizador final pode continuá-la.

• PRODUCT_DETAILS:
• Ação: o conversational_text_response fornece os detalhes do produto pedidos. O seu sistema deve apresentar estas informações de forma clara ao utilizador.
• A resposta também inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para obter resultados da pesquisa através da API Search principal.
• PRODUCT_COMPARISON:
• Ação: o conversational_text_response oferece uma comparação dos produtos especificados. O seu sistema deve apresentar estas informações de forma clara ao utilizador.
• A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para obter resultados da pesquisa através da API Search principal.
• BEST_PRODUCT:
• Ação: o conversational_text_response fornece recomendações ou informações sobre os produtos que melhor correspondem à consulta. O seu sistema deve apresentar estas informações.
• A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para obter resultados da pesquisa através da API Search principal.

Categoria 5. Refinamento de intenção

• INTENT_REFINEMENT:
• Ação: a resposta inclui conversational_text_response, um followup_question e refined_search (uma ou mais consultas de pesquisa sugeridas). A ordem de apresentação recomendada é a seguinte:
1. conversational_text_response
2. Sugestões refined_search: estas são ordenadas e classificadas, pelo que é importante apresentá-las pela mesma ordem da resposta.
3. Followup_question
• A resposta inclui refined_search (uma ou mais consultas de pesquisa sugeridas, ordenadas e classificadas) que devem ser usadas para obter resultados da pesquisa através da API Search principal.
• Para interações subsequentes, envie a resposta do utilizador juntamente com o conversation_id.

Mostrar consultas sugeridas para produtos

Veja como configurar a Pesquisa Google para apresentar perguntas e sugestões de produtos no agente de comércio conversacional.

Quando a API Conversational devolve consultas de refinedSearch, estas consultas representam excelentes oportunidades para orientar o utilizador final para produtos relevantes. Isto é particularmente valioso para a categoria 4 (consultas de procura de respostas de MDIs/CEs) e a categoria 5 (INTENT_REFINEMENT).

Recomendação

• Display: apresente as N principais (1 a 3, pendente de testes sobre o número ideal para a sua interface Web) refinedSearch consultas ao utilizador.
• Mecanismo: estas consultas sugeridas devem ser executadas através da API Search principal (SearchService.Search) em segundo plano ou após a interação do utilizador.
• Apresentação: mostre os resultados como carrosséis interativos ou cartões clicáveis, permitindo que o utilizador explore categorias de produtos relacionadas ou itens específicos. Isto oferece valor imediato e ajuda a colmatar a lacuna entre a interação conversacional e a descoberta de produtos.

Pedido de API de pesquisa:

Consulta de seguimento

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "Decorations",
  "visitorId": "test"
}
  

Eventos a enviar para o Vertex AI Search for commerce

É importante atribuir com precisão as consultas de pesquisa às interações conversacionais e usar as capacidades de análise completas na Vertex AI Search for commerce através da etiquetagem de eventos adequada:

1. Recuperar conversation_id. Quando faz uma chamada API conversationalSearch, é devolvido o ConversationalSearchResponse.conversation_id.
2. Etiquete eventos de utilizadores. Nos casos em que a resposta conversacional leva a uma consulta de pesquisa, como a apresentação de uma sugestão refined_search na qual o utilizador final clica, ou se o seu sistema executar automaticamente uma pesquisa com base na consulta refinada, tem de etiquetar esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao etiquetar corretamente UserEvent.conversation_id, a sua análise pode atribuir com precisão as consultas de pesquisa às interações de conversa anteriores, o que fornece estatísticas valiosas sobre o comportamento do utilizador e os caminhos de conversão.

Continue a conversa

Esta secção descreve como as sessões de agentes de comércio conversacional são mantidas pela API Conversational e continuam neste passo final.

A API Conversacional usa um conversation_id para gerir conversas em curso. Para garantir a consistência entre as respostas do MDG e os resultados da pesquisa, os pedidos Conversational API subsequentes têm de incluir SearchParams que reflitam a configuração das chamadas API Search principais.

Ver tabela

Processamento de sessões	Descrição	Integração da API de conversa
Iniciar uma conversa nova	Para iniciar uma nova conversa, o cliente omite o conversation_id do pedido da API.	Exemplo de pedido de API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Exemplo de resposta da API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Continue a conversa	A API Conversational devolve um conversation_id como parte da resposta da API. Este ID pode ser enviado nos pedidos subsequentes para continuar a mesma conversa. Isto ajuda a garantir que o agente de comércio conversacional responde às consultas do utilizador com base no histórico de conversas nessa sessão.	Exemplo de pedido de API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Exemplo de resposta da API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Garantir a consistência dos resultados da pesquisa	Para garantir que as respostas do MDG são consistentes com os resultados da pesquisa apresentados, o cliente tem de usar SearchParams no pedido da API Conversacional. Estes parâmetros de pesquisa devem ter a mesma configuração que a API Google Search principal.	Exemplo de pedido de API placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" search_params { filter: "filter" canonical_filter: "canonical_filter" sort_by: "sort_by" boost_spec { condition_boost_specs { condition: "condition" } } }

Processamento de sessões

• Inicie uma nova conversa:
  • Descrição: para iniciar uma nova conversa, o cliente omite o conversationId do pedido da API.
  • Quando iniciar uma nova conversa: um cliente quer iniciar uma nova conversa e, assim, receber um novo conversationId da resposta da API em vários cenários comuns da experiência do utilizador:
    • Novo separador ou sessão: quando um cliente abre o seu site num novo separador do navegador ou inicia uma sessão completamente nova.
    • Nova consulta original: em alguns designs da experiência do utilizador, se um cliente introduzir uma consulta nova e não relacionada, pode optar por reiniciar o fluxo de conversa para garantir o contexto mais relevante.
    • Botão Reiniciar conversa: se a sua interface Web fornecer um botão explícito Iniciar novo chat ou Repor conversa, clicar neste botão aciona uma nova sessão de conversa.
  • Integração da API de conversação: a resposta da API inclui um novo conversationId que é usado para pedidos subsequentes.
• Continuar a conversa:
  • Descrição: o Conversational API devolve um conversation_id como parte da resposta da API. Este ID tem de ser enviado em pedidos de seguimento para continuar a mesma conversa. Isto ajuda a garantir que o agente de comércio conversacional responde às consultas do utilizador com base no histórico de conversas nessa sessão, abrangendo o utilizador final query, o conversational_text_response e o followup_question.
  • Integração da API de conversação: o cliente passa o conversation_id da resposta anterior no ConversationalSearchRequest.
• Garantir a consistência dos resultados da pesquisa:
  • Description: para ajudar a garantir que as respostas do MDG são consistentes com os resultados da pesquisa apresentados ao utilizador, o cliente tem de usar searchParams no pedido Conversational API. Estes parâmetros de pesquisa devem ter a mesma configuração, como filtros e ordem de ordenação, que as chamadas Search API feitas para obter resultados de produtos.
  • Integração da API de conversação: o objeto searchParams no ConversationalSearchRequest deve ser preenchido de forma idêntica ao SearchRequest usado para a pesquisa de produtos principal.

Envie um pedido para o Vertex AI Search for commerce

Pode obter o conversation_id do armazenamento da sessão. O pedido deve incluir o novo cliente query, que pode ser uma resposta à pergunta da resposta anterior. O pedido também deve incluir o refined_search.query mais recente da resposta anterior se o utilizador final estiver a agir com base numa consulta refinada. Caso contrário, deve incluir uma consulta completamente nova e não relacionada, e o conversationId. Lembre-se de incluir sempre searchParamsconsistentes.

Nota: a manutenção ou a reposição do conversationId para uma nova consulta do utilizador final depende das suas escolhas específicas de UX e da experiência do utilizador selecionada. A conversationId funciona como a memória do sistema para uma determinada sessão de conversa.

• Cenário 1: uma única barra de pesquisa e uma conversa persistente: se a sua interface de pesquisa tiver apenas uma barra de pesquisa principal ou uma janela de conversa persistente, não repõe o conversationId, mesmo que o utilizador final escreva uma consulta nova e aparentemente não relacionada. O sistema usa o histórico de conversas existente (associado ao conversationId) para fornecer respostas contextualmente relevantes.
• Cenário 2: janela de conversa e janela de consulta separadas: se a sua interface de pesquisa apresentar uma janela de chat de conversa distinta e uma barra de consulta de pesquisa padrão separada (como uma caixa de pesquisa em todo o site), introduzir uma nova consulta na barra de pesquisa padrão pode sinalizar implicitamente uma intenção de iniciar uma nova pesquisa não relacionada, o que pode levar à reposição do conversationId para essa ação de pesquisa específica. No entanto, dentro da janela de conversa dedicada, o conversationId deve ser sempre mantido para garantir a continuidade.

Em última análise, a decisão sobre quando reutilizar ou repor o conversationId é uma escolha de design para otimizar a experiência de conversa para os seus clientes.

Método HTTP e ponto final (igual à consulta inicial)

POST https://retail.googleapis.com/v2alpha/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch
    

Pedido de API de conversação:

Consulta de seguimento

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {
    "filter": "categories:(\"Birthday Party Supplies\")"
  }
}
  

Resposta da API de conversação:

Resposta de seguimento

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}
  

Exemplos de um utilizador final que continua a receber perguntas:

• Pergunta do utilizador: Ajuda-me a planear uma festa.
• Resposta do sistema: Que tipo de festa está a planear?
• Resposta do utilizador: Uma festa de aniversário.

O que os retalhistas devem fazer com a resposta

A forma de renderizar campos é semelhante à da resposta inicial, mas tenha em atenção as alterações que refletem a conversa contínua:

• refined_search: este campo contém consultas atualizadas que incorporam a entrada mais recente do utilizador final. Deve atualizar a consola do cliente para a consulta atual em conformidade (por exemplo, mostrar que a consulta visível para o utilizador mudou de "decorações" para "decorações para festas de aniversário" ou "artigos para festas de aniversário"). As consultas refined_search podem ser usadas para chamadas à API Search principal (SearchService.Search) ou também podem ser apresentadas ao utilizador final como sugestões.
• conversational_text_response: apresentar a nova resposta de texto gerada pela IA relevante para a interação mais recente.
• followup_question: se a conversa precisar de continuar para um maior refinamento, é fornecido um novo followup_question.

Eventos a enviar para o Vertex AI Search for commerce

A etiquetagem de eventos é importante para atribuir com precisão consultas de pesquisa a interações conversacionais e usar as capacidades de estatísticas na Vertex AI Search for commerce.

Existem dois passos no processo de etiquetagem de eventos:

1. Recuperar conversation_id. Quando faz uma chamada API conversationalSearch, é devolvido o ConversationalSearchResponse.conversation_id.
2. Etiquete eventos de utilizadores. Nos casos em que a resposta conversacional leva a uma consulta de pesquisa, como a apresentação de uma sugestão refined_search, ou se o seu sistema executar automaticamente uma pesquisa com base na consulta refinada, tem de etiquetar esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id recebido no ConversationalSearchResponse.

Ao etiquetar corretamente UserEvent.conversation_id, as suas estatísticas podem atribuir com precisão as consultas de pesquisa às interações de conversa anteriores, o que fornece estatísticas valiosas sobre o comportamento do utilizador final e os caminhos de conversão.

Integre o agente com a filtragem de produtos conversacional

Este guia descreve como fazer a integração com a API Conversacional e a filtragem de produtos conversacional para oferecer uma experiência de compras com tecnologia de IA. Quando conversationalFilteringSpec.mode está definido como ENABLED, o seu sistema pode fazer a transição direta entre interações conversacionais abertas e filtragem de produtos guiada, oferecendo um percurso do utilizador altamente refinado.

Compreenda a interação

Quando o agente de comércio conversacional e a filtragem de produtos conversacional estão ativados, o sistema tira partido das vantagens de cada um. O agente de comércio conversacional processa consultas gerais, fornece respostas geradas pela IA e refina as intenções iniciais, enquanto a filtragem conversacional de produtos orienta os utilizadores através de seleções de atributos de produtos específicos com um modelo de interação simplificado baseado em chips ou mosaicos.

O ponto de interação e potencial transição entre estes dois modos ocorre quando a classificação da API Conversational Commerce leva a uma pesquisa orientada para produtos, especificamente SIMPLE_PRODUCT_SEARCH. Neste ponto, a API pode fornecer uma consulta de pesquisa direta ou, se a intenção do utilizador puder ser refinada, aciona um fluxo de filtragem guiada através da filtragem de produtos conversacional.

Um princípio fundamental desta integração é que toda a entrada de texto livre é processada pela API Conversational Commerce, enquanto os cliques em respostas sugeridas que aparecem como chips são processados pela filtragem de produtos conversacional.

Envie uma consulta do utilizador

Exemplo de entrada do utilizador: ajuda-me a planear uma festa

Para ativar o agente de comércio conversacional e a filtragem de produtos conversacional, certifique-se de que o seu ConversationalSearchRequest inclui esta configuração:

Pedido de API Conversational Commerce: consulta inicial

{
  "query": "Help me plan a party",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "visitorId": "your_visitor_id",
  "conversationId": "", // Leave empty for the first query, or populate for ongoing conversation
  "searchParams": {
    // IMPORTANT: These search parameters should mirror the configuration
    // of your Commerce Search API calls to ensure consistency.
    "filter": "categories:(\"Party Supplies\" OR \"Decorations\" OR \"Food & Drink\")"
  },
  "userInfo": {
    // Optional: User information for enhanced personalization
  },
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED" // Crucial for enabling product filtering
  }
}

As principais configurações são:

• Conversational_filtering_mode: ENABLED: definir este campo como ENABLED no seu conversationalFilteringSpec informa a API de que o seu sistema pode processar a filtragem de produtos conversacional, o que permite à API fornecer respostas relevantes específicas da filtragem.

Resposta inicial: refinamento da intenção

O campo userQueryTypes continua a ser fundamental para compreender a intenção do utilizador. Para uma consulta inicial ampla, como Ajuda-me a planear uma festa, a API vai classificá-la provavelmente como INTENT_REFINEMENT se não for imediatamente claro que se trata de uma pesquisa de produtos mais específica.

Resposta da Google

Resposta da API Conversational Commerce: consulta inicial

{
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "To plan a party, you'll need decorations, snacks, party supplies, drinks, and a cake. You can find a wide variety of decorations, snacks, and drinks. For party supplies, you can find everything from plates and cups to balloons and streamers. And for cake, you can choose from a variety of flavors and sizes.",
  "followupQuestion": {
    "followupQuestion": "What kind of party are you planning?"
  },
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "Decorations" },
    { "query": "Snacks" },
    { "query": "Party Supplies" },
    { "query": "Drinks" },
    { "query": "Cake" }
  ],
  "state": "SUCCEEDED"
}

Ação

1. Apresentar o conversationalTextResponse.
2. Apresentar as sugestões refinedSearch como chips clicáveis para Decorações, Snacks. Em alternativa, chame a API Commerce Search em paralelo usando as consultas refined_search para apresentar resultados de produtos relevantes, como Decorações, Snacks, como um carrossel, juntamente com a troca de mensagens conversacional.
3. Apresentar o followupQuestion: que tipo de festa está a planear?
4. Permitir a introdução de texto livre pelo utilizador para avançar na conversa.

Etiquetagem de eventos e estatísticas

Para garantir estatísticas e atribuição precisas para a interação de conversa inicial:

• Recuperar conversation_id. Capture o conversation_id a partir do ConversationalSearchResponse. Este ID é fundamental para associar todas as ações subsequentes a esta sessão de conversa específica.
• Etiquete eventos de utilizadores. Se a resposta conversacional originar uma consulta de pesquisa, como o seu sistema executar automaticamente uma pesquisa com base numa consulta refined_search, ou se o utilizador clicar numa sugestão refined_search, tem de etiquetar esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id.

Consulta de seguimento

Quando o utilizador responde ao followupQuestion, a conversa é refinada.

Exemplo de introdução do utilizador: Uma festa de aniversário

Refinamento da intenção | Fragmentos do código

Pedido de API Conversational Commerce: consulta de seguimento

{
  "query": "A birthday party", // New query continuing the conversation from the previous turn
  "placement": "projects/799252947591/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "test", // Or your actual visitor_id
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // conversation_id from previous response
  "searchParams": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Resposta da API Conversational Commerce: consulta de seguimento

{
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "userQueryTypes": ["INTENT_REFINEMENT"],
  "conversationalTextResponse": "Great! For a birthday party, you might be interested in specific themes or age-group appropriate items.",
  "followupQuestion": {
    "followupQuestion": "What's the age group or theme?"
  },
  "refinedSearch": [
    { "query": "Birthday party decorations" },
    { "query": "Birthday party supplies" }
  ],
  "state": "SUCCEEDED"
}

Ação

1. Tal como na resposta inicial, atualize a interface Web com as novas sugestões conversationalTextResponse, refinedSearch e followupQuestion.
2. Continuar o fluxo da conversa, pedindo mais detalhes.

Etiquetagem de eventos e estatísticas

Quando o utilizador continua a conversa:

• Recuperar conversation_id. Certifique-se de que o conversation_id do ConversationalSearchResponse anterior é transmitido no ConversationalSearchRequest atual.
• Etiquete eventos de utilizadores. Se a resposta conversacional originar uma nova consulta de pesquisa, por exemplo, devido a um utilizador clicar numa sugestão refined_search ou o seu sistema fazer uma chamada de pesquisa paralela, etiquete esse evento de utilizador de pesquisa subsequente (UserEvent) com o mesmo conversation_id. Isto ajuda a acompanhar o percurso conversacional de várias interações.

Transição para a filtragem de produtos conversacional

À medida que a conversa se torna mais específica, o sistema pode classificar a intenção como SIMPLE_PRODUCT_SEARCH e, se for adequado, acionar a filtragem de produtos conversacional.

Exemplo de entrada do utilizador: tema de princesas

Pedido de API Conversational Commerce: consulta de seguimento

{
  "query": "Princess theme",
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Possíveis resultados para a pesquisa de produtos principal

Quando uma consulta é classificada como SIMPLE_PRODUCT_SEARCH, existem duas respostas possíveis da API, consoante o acionamento do filtro de produtos conversacional. A principal diferença reside na presença e no conteúdo do campo conversationalFilteringResult.

Resultado 1: a filtragem é acionada

Isto ocorre quando a consulta é suficientemente essencial para ser refinada ainda mais por atributos do produto. A resposta inclui conversationalFilteringResult, que a sua interface Web deve priorizar.

Resposta da API Conversational Commerce: transição para a filtragem de produtos:

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday decorations" }
  ],
  "conversationalFilteringResult": {
    "followupQuestion": "What specific type of princess decoration are you looking for?",
    "suggestedAnswers": [
      { "answer": "Balloons", "query": "princess birthday balloons" },
      { "answer": "Streamers", "query": "princess birthday streamers" },
      { "answer": "Tablecloths", "query": "princess birthday tablecloths" }
    ]
  },
  "state": "SUCCEEDED"
}

Ação

A consulta foi classificada como SIMPLE_PRODUCT_SEARCH. Neste caso, aciona a filtragem de produtos conversacional. No entanto, pode não acionar a filtragem de produtos conversacional.

• Dê prioridade à interface Web de filtragem de produtos conversacional:quando conversationalFilteringResult está preenchido, indica que introduziu o modo de filtragem de produtos. A sua interface Web deve realçar o followupQuestion, que aparece na interface do utilizador como algo semelhante a Que tipo específico de decoração de princesa procura?, e o suggestedAnswers, como botões clicáveis para Balões, serpentinas e toalhas de mesa.
• Apresentar resultados de produtos: chame imediatamente a API Retail Search com o termo de pesquisa refined_search.query (decorações de aniversário de princesa) para apresentar os resultados de produtos iniciais juntamente com as opções de filtragem.
• Prática recomendada de experiência do utilizador: deve existir uma única barra de introdução de texto livre persistente para toda a experiência. Esta barra permanece ativa em todos os momentos, inclusive durante um fluxo de filtragem de produtos conversacional. Quando o conversationalFilteringResult está ativo e apresenta respostas sugeridas como chips clicáveis, os utilizadores têm duas opções claras:
• Continue o fluxo de filtragem clicando numa resposta sugerida.
• Inicie uma nova interação conversacional escrevendo uma nova consulta na barra de texto ativa. Esta nova entrada aciona sempre uma nova chamada à API Conversational Commerce, terminando efetivamente o fluxo de filtragem atual.

Nota: esta escolha de design está alinhada com o princípio fundamental de que a introdução de texto livre é processada pela API Conversational Commerce, enquanto os cliques em respostas sugeridas são processados pela filtragem de produtos conversacional.

Resultado 2: não é acionada qualquer filtragem

Se a consulta já for suficientemente específica ou não se adequar a uma filtragem adicional, a resposta não inclui o campo conversationalFilteringResult. Neste caso, deve continuar com uma pesquisa padrão.

Ação

• Trate a interação como o fim do fluxo de conversa e use a consulta refined_search para chamar a API Retail Search e apresentar uma página de resultados de produtos padrão.

Etiquetagem de eventos e estatísticas

Quando a conversa passa para a filtragem de produtos:

• Recuperar conversation_id. Continuar a usar o mesmo conversation_id.
• Etiquete eventos de utilizadores. Se a transição levar a uma pesquisa imediata, etiquete-a UserEvent com conversation_id. É importante que, quando o utilizador interage com o suggestedAnswers, por exemplo, quando um utilizador final clica em Balões, esta ação também deve acionar um UserEvent, como um evento filter ou um novo evento search, que esteja etiquetado com o mesmo conversation_id. Isto permite a atribuição de ações de filtragem no fluxo de conversa.

Continue a filtragem de produtos conversacional

Quando o utilizador seleciona um suggestedAnswer, envie um novo ConversationalSearchRequest.

Exemplo de entrada do utilizador (clicar numa resposta sugerida): Balões

Pesquisa simples de produtos | Fragmentos do código

Pedido da API Conversational Commerce: continuar a filtrar

{
  "query": "Balloons", // The selected answer
  "placement": "projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/placements/default_search",
  "branch": "projects/{project_id}/locations/{location_id}/catalogs/{catalog_id}/branches/default_branch",
  "visitorId": "your_visitor_id",
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb", // Maintain conversation ID
  "searchParams": {},
  "userInfo": {},
  "conversationalFilteringSpec": {
    "conversational_filtering_mode": "ENABLED"
  }
}

Resposta da API Conversational Commerce: continuar a filtrar

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "1577511e-36ed-4054-8e07-48d1ca016bcb",
  "refinedSearch": [
    { "query": "princess birthday balloons" }
  ],
  "state": "SUCCEEDED"
}

Ação

A API responde com uma consulta SIMPLE_PRODUCT_SEARCH, mas sem o campo conversationalFilteringResult, o que indica que o fluxo de filtragem guiada foi concluído.

• Use a refinedSearchconsultafinal(princess birthday balloons) para fazer uma chamada direta à API Retail Search.
• Apresentar os resultados finais dos produtos ao utilizador. Neste ponto, a conversa pode terminar ou o utilizador pode introduzir uma nova consulta para iniciar uma nova interação.

Etiquetagem de eventos e estatísticas

Para cada passo no processo de filtragem de produtos:

• Recuperar conversation_id. Use sempre o mesmo conversation_id para todos os pedidos na sessão de filtragem.
• Etiquete eventos de utilizadores. Cada interação do utilizador com um suggestedAnswer, como um clique, deve acionar um UserEvent relevante, como um evento filter ou um novo evento search se for formulada uma nova consulta. Esta UserEvent tem de ser etiquetada com o conversation_id para acompanhar com precisão o percurso de filtragem e o respetivo impacto na conversão.

Recomendações e seleções de design da interface do utilizador

A interação entre o agente de comércio conversacional e a filtragem de produtos conversacional oferece uma flexibilidade significativa. Seguem-se algumas considerações importantes da experiência do utilizador para criar uma experiência simples e intuitiva:

• Barra de entrada única: deve existir apenas uma barra de entrada de texto livre para toda a experiência. Não existe uma barra de introdução separada e dedicada para a filtragem de produtos conversacional. Isto simplifica a interface do utilizador e mantém a interação consistente.
• Transições perfeitas: crie a sua interface Web para que as transições entre respostas conversacionais, consultas sugeridas e opções de filtragem pareçam naturais e intuitivas.
• Orientações claras: use indicações visuais, como estilos de botões distintos para respostas sugeridas, em vez de introdução geral, e instruções claras para orientar o utilizador sobre como interagir em cada fase.
• Equilibrar o controlo: o utilizador deve sentir sempre que tem o controlo da direção da conversa.
• Filtragem vs. formato livre: a barra de entrada de texto livre única permanece ativa em todos os momentos. Isto dá ao utilizador uma escolha constante: pode clicar numa resposta sugerida para continuar a refinar a pesquisa ou escrever uma nova consulta na barra de texto para iniciar uma nova interação conversacional. Este design garante que, mesmo durante um fluxo de filtragem, o utilizador pode mudar para um tópico diferente se as suas necessidades mudarem.
• Opção de reposição: disponibilize uma opção clara Iniciar nova conversa ou Repor filtros para permitir que os utilizadores reiniciem o processo de pesquisa ou filtragem.
• Persistência visual: mesmo ao fazer a transição para a filtragem de produtos, a manutenção do histórico de conversas na janela de chat, como a apresentação de perguntas e respostas anteriores, pode melhorar o contexto e a experiência do utilizador.

Considerações e práticas recomendadas adicionais

É necessário ter em conta considerações e práticas recomendadas adicionais ao implementar a interface do agente de comércio conversacional:

• Consistência do ID de visitante: ajuda a garantir que um visitor_id exclusivo é enviado de forma consistente com cada pedido de um determinado utilizador final. Isto é vital para uma personalização e um treino de modelos precisos. Idealmente, este identificador deve permanecer consistente para um utilizador final em todas as sessões e estados de início ou fim de sessão.
• Gestão de filiais: embora default_branch seja comum, certifique-se de que está a usar o ID da filial correto se o seu catálogo de produtos estiver estruturado com várias filiais.
• Interação com a API Search: para SIMPLE_PRODUCT_SEARCH e todos os casos em que refined_search é fornecido, lembre-se de fazer uma chamada separada à API Search principal (SearchService.Search) usando o query do campo refined_search ou a consulta original para obter as fichas dos produtos reais. A API Conversacional foca-se principalmente na experiência de conversa e na compreensão da intenção do utilizador, em vez de devolver diretamente resultados de produtos.
• Design da interface do utilizador: crie a sua interface Web para apresentar claramente as opções conversational_text_response, followup_question e refined_search de forma intuitiva para orientar o utilizador.

O que se segue?

Para ver recursos de apoio técnico adicionais, consulte as Perguntas frequentes sobre as funcionalidades de conversa.