Guía para desarrolladores de agentes de comercio conversacional

En esta guía, se detalla cómo realizar la integración con la API de Conversational para proporcionar experiencias de chat dinámicas potenciadas por IA a tus clientes. Si comprendes los diferentes tipos de búsquedas y aprovechas las respuestas de la API, puedes ofrecer búsquedas de productos relevantes, responder las consultas de tus clientes y guiar a tus usuarios finales en su recorrido de compra.

El objeto conversationalFilteringMode en la API de Conversational deja en claro las diferencias entre el agente de comercio conversacional y el filtrado de productos conversacional.

Configuración

La API de Conversational admite la función del agente de Conversational Commerce:

La API de Conversational permite una experiencia de chat en la que los usuarios envían consultas y el sistema devuelve una respuesta de texto, tipos de consultas clasificadas y posibles opciones de búsqueda refinadas.

Esta API funciona como un servicio de transmisión, lo que permite la detección anticipada de la intención de la búsqueda. Las interacciones posteriores en la conversación requieren adjuntar un conversation_id.

Para devolver resultados de la búsqueda, se debe llamar a la API de Retail heredada en paralelo con la API de Conversational.

Envía una consulta desde el usuario final

En esta sección, se describe cómo iniciar una experiencia de agente de comercio conversacional. Por ejemplo, el usuario podría ingresar Ayúdame a planificar una fiesta en el campo de búsqueda.

Envía una solicitud a Vertex AI Search for Commerce

Existen dos extremos de API diferentes:

  1. Se debe usar la API de Conversación para recuperar la experiencia de conversación.
  2. Se debe usar la API de Search principal para recuperar los resultados de la búsqueda.

Extremo 1: Solicitud a la API de Conversational

  • Debes crear una solicitud de agente de comercio conversacional configurando la entrada del usuario como la consulta.
  • La solicitud debe enviarse como una solicitud HTTP POST al extremo projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Método y extremo HTTP

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

Solicitud a la API conversacional:

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: Es el nombre del recurso de la posición (por ejemplo, projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Este es un parámetro de ruta de acceso y es obligatorio.
  • query: Es la búsqueda sin procesar de tu usuario. Este campo es obligatorio.
  • branch: Es el nombre del recurso de la rama, como projects/P/locations/L/catalogs/C/branches/B. Si no se establece, se usa default_branch. Este campo es obligatorio.
  • visitorId: Es un identificador único para hacer un seguimiento de los visitantes. Este campo es obligatorio.
  • conversationId: Es un ID único para hacer un seguimiento de las sesiones de conversación. Para la solicitud initial en una conversación nueva, este campo debe estar vacío. Para las solicitudes posteriores dentro de la misma conversación, se debe establecer en el conversation_id recibido en el ConversationalSearchResponse anterior.
  • searchParams: (Opcional) Parámetros de la Búsqueda principal estándar, como filter, canonicalFilter, sortBy y boostSpec. Es fundamental que estos parámetros reflejen la configuración que se usa en las llamadas principales a la API de Search para garantizar la coherencia entre las respuestas del LLM y los resultados de la búsqueda de productos que se muestran.
  • userInfo: (Opcional) Es la información del usuario para una personalización mejorada. Puede incluir userId, user_agent, direct_user_request (booleano).
  • conversationalFilteringSpec: (Opcional) Especifica el modo de filtrado conversacional. Si no se configura, se INHABILITA de forma predeterminada.

    mode: Integra la API de Conversational con uno de estos tres modos para controlar el filtrado de productos conversacionales:

    • DISABLED: En este modo, el cliente solo implementa la búsqueda del agente de Conversational Commerce. Este es el modo preferido para esta guía de implementación sobre la búsqueda de agentes de comercio conversacional.

      • Solicitud a la API de muestra

              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
        }

      Ejemplo de respuesta de la API

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
    • ENABLED: En este modo, el cliente implementa todas las capacidades conversacionales, lo que incluye la búsqueda de agentes de comercio conversacional y el filtrado de productos conversacionales.

      • Consulta la guía adicional sobre cómo integrar ambos productos conversacionales.

      Solicitud a la API de muestra

              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
        }

      Ejemplo de respuesta de la 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: Si se elige, el cliente solo implementa el filtrado de productos conversacional. Con este modo seleccionado, el usuario solo experimenta el filtrado conversacional de productos sin generar una respuesta de LLM, una clasificación de búsqueda ni búsquedas sugeridas.

      • Para obtener más información, consulta la guía para desarrolladores de filtros de productos conversacionales.

Extremo 2: Solicitud a la API de Core Search

Existen dos enfoques principales para mostrar los resultados de la búsqueda en tu interfaz web.

Opción 1: Mostrar siempre los resultados de la búsqueda

Si el diseño de la experiencia del usuario indica que los resultados de la búsqueda siempre deben mostrarse independientemente del resultado conversacional, como en un área de resultados de la búsqueda dedicada junto al chat, envía la búsqueda original del usuario a la API principal de Product Search con tu llamada a la API de Conversational. Esto ayuda a garantizar que las fichas de productos estén disponibles de inmediato.

Opción 2: Mostrar resultados de la búsqueda basados en la respuesta conversacional

Si el diseño de la experiencia del usuario es más dinámico y solo deseas mostrar los resultados de la búsqueda según la respuesta de la API de Conversational, por ejemplo, solo para las búsquedas de SIMPLE_PRODUCT_SEARCH o cuando se proporcionan sugerencias de refined_search, espera la respuesta de la API de Conversational antes de enviar cualquier búsqueda a la API principal de Product Search. Si hay una respuesta, usa la búsqueda refined_search proporcionada para recuperar los resultados de productos.

Independientemente de la opción de interfaz de usuario que elijas, cuando necesites recuperar resultados de productos reales, puedes llamar a la API de Retail. Para obtener más información, consulta Comprende los tipos de búsquedas y las acciones de los comercios.

Método y extremo HTTP

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

Solicitud principal a la API de Product Search:

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 (obligatorio): Es el nombre del recurso de la configuración de publicación de la Búsqueda de Retail o de la posición heredada. Ejemplo: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
  • query: Obligatorio. Es la búsqueda. Puede ser la entrada sin procesar del usuario, como Ayúdame a planificar una fiesta, o un refinedSearch.query más optimizado (como suministros para la planificación de fiestas, decoraciones) que se obtiene de la respuesta de la API de Conversational Commerce.
  • visitorId: Obligatorio. Es un identificador único para hacer un seguimiento de los visitantes. Debe ser coherente con el visitorId que se envía a la API de Conversational Commerce para el mismo usuario final.
  • branch (obligatorio): Es el nombre del recurso de la rama, como projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
  • pageSize (opcional): Es la cantidad máxima de productos que se mostrarán.
  • filter (opcional): Se usa para filtrar los resultados de la búsqueda. Aquí es donde aplicarías los filtros que reflejan lo que envías en `searchParams` a la API de Conversational Commerce para garantizar la coherencia.
  • orderBy (opcional): Especifica el orden en el que se muestran los productos (por ejemplo, por relevancia o por precio).
  • userInfo (opcional): Es la información del usuario para la personalización, que debe ser coherente con la llamada a la API de Conversational Commerce.
  • searchMode (opcional): Define el comportamiento de la búsqueda. PRODUCT_SEARCH se usa con frecuencia para las consultas generales sobre productos.

Comprende la respuesta

En este muestra de código, se muestra una respuesta de la API de Conversational Commerce.

La respuesta de la API (ConversationalSearchResponse) incluye query_types, conversational_text_response (si corresponde), opciones de refined_search y, posiblemente, un followup_question o un conversational_filtering_result. El conversation_id es fundamental para continuar la sesión.

Respuesta de Vertex AI Search for Commerce

En este muestra de código, se muestra una respuesta de la API de Conversational:

Respuesta 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"
    }

Qué deben hacer los minoristas con la respuesta (general)

Renderiza estos campos de la respuesta:

  • user_query_types: Este campo proporciona las clasificaciones de la intención del usuario. Para obtener información detallada sobre las acciones basadas en estos tipos, consulta Información sobre los tipos de búsquedas y las acciones de los comercios.
  • conversation_id: Puedes almacenar este ID único en el almacenamiento de sesión del navegador o en un almacenamiento similar del cliente para mantener la sesión de conversación con el servidor. Esto es fundamental para distinguir entre varias conversaciones en curso de un solo comprador. Tu modelo conserva el contexto para un conversation_id determinado. Si envías un nuevo conversation_id, se iniciará una sesión nueva. Se recomienda definir la duración de la sesión, por ejemplo, 30 minutos de inactividad.
  • refined_search: Es una lista de búsquedas refinadas propuestas que se usan para recuperar los resultados de la búsqueda pertinentes. En el caso de SIMPLE_PRODUCT_SEARCH, siempre es una sola búsqueda. Para otras búsquedas que buscan respuestas de LLM, es una o más. Las búsquedas de refined_search se pueden usar para llamadas a la API de Search principal (SearchService.Search) o también se pueden mostrar a tu usuario como sugerencias.
  • conversational_text_response: Muestra este texto al usuario como la respuesta principal generada por IA a su búsqueda.
  • followup_question: Opcional. Se muestra el followup_question.
  • state: Este campo indica el estado de la generación de respuesta ("STREAMING" o "SUCCEEDED"). Puedes usarlo para obtener comentarios sobre la experiencia del usuario, por ejemplo, mostrar un indicador de carga hasta que se muestre "SUCCEEDED". Encontrarás más detalles al respecto en la siguiente sección.

Información sobre la API de transmisión

La API de Conversational Commerce funciona como una API de transmisión. Esto significa que tu usuario recibe partes de la respuesta en varios fragmentos en lugar de una sola carga útil completa.

El primer fragmento de la respuesta incluye las búsquedas query_types y refined_search, y su state se indica como STREAMING. Esta detección temprana de la intención y la disponibilidad inmediata de los refinamientos de la búsqueda permiten que tu modelo tome decisiones rápidas sobre cómo controlar la búsqueda del usuario y cómo administrar su experiencia en relación con la latencia de las respuestas del LLM:

  • Para los tipos de preguntas que no esperan una respuesta de texto conversacional, como SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS y STORE_RELEVANT:
    • Como los query_types se encuentran en el primer fragmento, tu sistema sabe de inmediato que no habrá una respuesta de LLM. Puedes continuar con el manejo predefinido para estos tipos, como mostrar un mensaje estático o redireccionar al equipo de asistencia, sin esperar más resultados conversacionales.
    • Específicamente para SIMPLE_PRODUCT_SEARCH, tu sistema puede realizar de inmediato una llamada directa a la API de Search principal con la búsqueda refined_search que se recibió en el primer fragmento. Esto ayuda a garantizar que los resultados de la búsqueda se muestren con una demora mínima, lo que cumple con los ANS típicos de la experiencia de búsqueda.
  • Para los tipos de preguntas que sí esperan una respuesta de texto conversacional, como INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON y BEST_PRODUCT:
    • Recibirás las búsquedas query_types y refined_search en el fragmento inicial. Puedes iniciar de inmediato una llamada paralela a la API de Search principal con estas búsquedas de refined_search para comenzar a cargar los resultados de los productos.
    • Luego, se transmiten fragmentos posteriores que contienen diferentes secciones de la respuesta de texto conversacional. Durante este tiempo, el state permanece "STREAMING".
    • Por último, el último fragmento incluye la respuesta de texto conversacional completa y su state cambia a "COMPLETED".
    • Este enfoque de transmisión permite una experiencia fluida para el usuario final, en la que los resultados de la búsqueda pueden comenzar a cargarse mientras se genera el resumen de IA. Puedes elegir mostrar un indicador de carga para la respuesta conversacional o presentar la respuesta conversacional después de que se transmita por completo.

Comprende los tipos de búsquedas y las acciones de los comercios

El campo query_types de la respuesta es una lista que indica las clasificaciones de la intención del usuario. Tu sistema debe controlar estos casos de la siguiente manera. Ten en cuenta que conversational_text_response hace referencia a la respuesta de lenguaje natural generada por IA de la API.

El agente de Conversational Commerce usa categorías de búsquedas para determinar si se genera una respuesta basada en LLM y cómo las APIs de Conversational y Search manejan las búsquedas de los usuarios finales en los siguientes casos:

Categorías Clasificaciones de búsquedas
#1. Consultas irrelevantes que no requieren una respuesta del LLM
  • QUERY_TYPE_UNSPECIFIED: Tipo de búsqueda no especificado.
  • RETAIL_IRRELEVANT: Son las búsquedas irrelevantes para el dominio de venta minorista, por ejemplo, una búsqueda adversarial (como cómo hacer una bomba),una búsqueda conversacional (como ¿cómo estás?) o una búsqueda de jailbreak (como escribe un poema).
  • BLOCKLISTED: Son las búsquedas que los clientes de comercio electrónico bloquearon de forma explícita (por ejemplo, ¿Cuáles son los efectos secundarios del Advil?).
#2. Consultas de asistencia e información
  • ORDER_SUPPORT: Consulta complementaria o de asistencia (como Hacer un seguimiento de mi pedido, estado del pedido 12345)
  • DEALS_AND_COUPONS: Son las búsquedas relevantes para ofertas, promociones, ofertas de productos y descuentos (como ¿Hay ofertas para el Día de Acción de Gracias?).
  • STORE_RELEVANT: Son las búsquedas relevantes para las ubicaciones de las tiendas, incluidos los horarios de atención y la disponibilidad de productos en stock (por ejemplo, ¿Tenemos leche en stock?).
  • RETAIL_SUPPORT: Son las búsquedas relevantes para las compras, incluidas las formas de pago (¿Qué formas de pago aceptan?).
#3. Búsquedas de palabras clave que no requieren un LLM

Solicitud a la 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"
}

Respuesta de la API de conversación:

Respuesta inicial

{
  "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"],
  "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9",
  "refinedSearch": [
    {
      "query": "monster energy drinks"
    }
  ]
}

Solicitud a la API de búsqueda:

Consulta de seguimiento

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  • SIMPLE_PRODUCT_SEARCH: Búsqueda básica de productos, como Vestido rojo o Mostrar algunas bebidas Monster.
#4. Preguntas que buscan respuestas de LLM

Solicitud a la 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"
  }

Respuesta de la API de conversación:

Respuesta 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"
    }
  ]
}

Solicitud a la API de búsqueda:

Consulta de seguimiento

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "1% milk",
  "visitorId": "test"
}
  • PRODUCT_DETAILS: El usuario busca detalles y especificaciones del producto, como Muéstrame las especificaciones de [nombre del producto]. ¿Cuál es el contenido de proteínas de la leche al 2%?
  • PRODUCT_COMPARISON: Comparación de productos, como compara [nombre del producto] y [nombre del producto], compara la leche al 1% con la leche al 2%.
  • BEST_PRODUCT: Son las búsquedas con el patrón más coincidente, como ¿Cuál es la galleta más saludable? ¿Cuál es la mejor marca de leche?
5. Refinamiento del intent

Solicitud a la 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"
}

Respuesta de la API de conversación:

Respuesta 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: El tipo no está claro y es posible que se necesite una conversación de seguimiento o una definición más precisa para aclarar el tipo, como Ayúdame a planificar una fiesta. Esta suele ser la intención más popular en las conversaciones.

Categoría 1 Consultas irrelevantes que no requieren una respuesta del LLM

  • QUERY_TYPE_UNSPECIFIED:
    • No se proporciona ningún conversational_text_response.
    • Acción: Controla como un caso predeterminado o de error. Puedes pedirle al usuario que aclare su duda o dirigirlo a donde puede recibir ayuda general.
  • RETAIL_IRRELEVANT:
    • No se proporciona ningún conversational_text_response.
    • Acción: Para controlar esto, muestra un mensaje adecuado, como No puedo responder esa pregunta o Soy un asistente de compras. ¿En qué puedo ayudarte?, según lo defina el diseño de tu aplicación.
  • BLOCKLISTED:
    • No se proporciona ningún conversational_text_response.
    • Acción: Controla la solicitud según tu política de lista de bloqueo. Por lo general, se muestra un mensaje genérico que indica que no se puede completar la solicitud.

Categoría 2. Consultas de asistencia e información

En estos tipos, la API no proporciona un conversational_text_response directo de forma predeterminada, pero tienes opciones para dirigir a los vínculos o recursos correctos.

  • ORDER_SUPPORT:
    • Acción predeterminada: No se proporciona ningún conversational_text_response. Tu interfaz web debe mostrar algún mensaje estándar, vínculos relevantes o redireccionar la búsqueda a tu propia API de asistencia dedicada o canal de atención al cliente.
  • DEALS_AND_COUPONS:
    • Acción predeterminada: No se proporciona ningún conversational_text_response. Tu interfaz web debe mostrar algún mensaje estándar, vínculos relevantes o redireccionar la búsqueda a tu sistema de ofertas o promociones.
  • STORE_RELEVANT:
    • Acción predeterminada: No se proporciona ningún conversational_text_response. Tu interfaz web debe mostrar algún mensaje estándar, vínculos relevantes o redireccionar la búsqueda a tu propio localizador de tiendas o sistema de información.
  • RETAIL_SUPPORT:
    • Acción predeterminada: No se proporciona ningún conversational_text_response. Tu interfaz web debe mostrar algún mensaje estándar, vínculos relevantes o redireccionar la búsqueda a tu propio sistema de preguntas frecuentes y de información.

Categoría 3. Búsquedas por palabras clave que no requieren respuestas de LLM

  • SIMPLE_PRODUCT_SEARCH:
    • No se genera ninguna respuesta de texto conversacional.
    • Acción: La respuesta de la API siempre devuelve una sola búsqueda de refined_search. Esta consulta refinada actúa como un término de búsqueda sugerido. Realiza una llamada directa a la API de Search principal (SearchService.Search) y recupera los resultados de productos relevantes con la consulta original o la consulta refined_search. La refined_search.query podría no provenir directamente de la entrada del usuario final actual, sino que también podría derivarse del contexto del historial de chat, por ejemplo, si un usuario final anteriormente refinó vestido de fiesta a vestidos rojos, la búsqueda refinada podría convertirse en vestido rojo de fiesta.
      • Para interfaces de conversación (como chatbots): Se recomienda mucho usar el refined_search.query que proporciona la API. En un flujo de conversación, la API optimiza automáticamente las búsquedas en lenguaje natural, como "¿puedes ayudarme a encontrar bananas?", y las convierte en un término de búsqueda de productos preciso ("bananas"), lo que genera resultados de productos más relevantes.
      • Para las experiencias de búsqueda principales (como la página de resultados de la búsqueda): Tienes la flexibilidad de usar el refined_search.query de la API o la búsqueda original proporcionada por el usuario final, ya que es más probable que la búsqueda original ya sea un término de búsqueda de productos preciso. Elige la opción que mejor se adapte a tu interfaz web y a tu estrategia de visualización de resultados de la búsqueda.
    • Opciones de experiencia del usuario: La conversación no necesita finalizar para las búsquedas de SIMPLE_PRODUCT_SEARCH. Tu usuario puede continuar la conversación pasando el conversation_id en solicitudes posteriores.
      • Opción A: Finalizar la interfaz web conversacional: Muchos minoristas optan por dirigir al usuario a una página de resultados de búsqueda estándar una vez que se detecta un SIMPLE_PRODUCT_SEARCH, lo que cierra la ventana de chat. En este caso, si el usuario final ingresa una nueva búsqueda en el cuadro de búsqueda estándar sin el conversation_id anterior, se tratará como una conversación nueva y separada, y se emitirá un nuevo conversation_id.
      • Opción B: Continuar con la interfaz web de conversación: Los minoristas pueden optar por mantener abierta la ventana de chat. Esto permite que el usuario vuelva a un modo conversacional. La decisión de implementar la opción A o B depende por completo de la experiencia del usuario que prefiera el comercio.

    Para atribuir con precisión las búsquedas a las interacciones conversacionales y usar todas las capacidades de análisis en Vertex AI Search para el comercio, es fundamental etiquetar los eventos de forma adecuada:

    1. Recupera conversation_id. Cuando realizas una llamada a la API de conversationalSearch, se devuelve el objeto ConversationalSearchResponse.conversation_id.
    2. Etiqueta eventos de usuario. En los casos en que la respuesta conversacional genere una búsqueda, por ejemplo, si tu sistema ejecuta automáticamente una búsqueda basada en la búsqueda refinada de SIMPLE_PRODUCT_SEARCH, debes etiquetar ese evento del usuario de búsqueda posterior (UserEvent) con el mismo conversation_id que se recibió en el ConversationalSearchResponse.

Si etiquetas correctamente UserEvent.conversation_id, tus estadísticas podrán atribuir con precisión las búsquedas a las interacciones conversacionales anteriores, lo que te proporcionará estadísticas valiosas sobre el comportamiento de los usuarios y las rutas de conversión.

Categoría 4. Preguntas que buscan respuestas de LLM

Para estos tipos de búsquedas, la API genera una conversational_text_response (respuesta del LLM) y también puede proporcionar una o más búsquedas refined_search. La conversación no finaliza y el usuario final puede continuarla.

  • PRODUCT_DETAILS:
    • Acción: El conversational_text_response proporciona los detalles del producto solicitados. Tu sistema debe mostrar esta información claramente al usuario.
    • La respuesta también incluye refined_search (una o más sugerencias de búsquedas, ordenadas y clasificadas) que se deben usar para recuperar los resultados de la búsqueda con la API principal de Search.
  • PRODUCT_COMPARISON:
    • Acción: El conversational_text_response proporciona una comparación de los productos especificados. Tu sistema debe mostrar esta información claramente al usuario.
    • La respuesta incluye refined_search (una o más búsquedas sugeridas, ordenadas y clasificadas) que se deben usar para recuperar los resultados de la búsqueda con la API de Search principal.
  • BEST_PRODUCT:
    • Acción: conversational_text_response proporciona recomendaciones o información sobre los productos que mejor coinciden con la búsqueda. El sistema debería mostrar esta información.
    • La respuesta incluye refined_search (una o más búsquedas sugeridas, ordenadas y clasificadas) que se deben usar para recuperar los resultados de la búsqueda con la API de Search principal.

Categoría 5 Perfeccionamiento del intent

  • INTENT_REFINEMENT:
    • Acción: La respuesta incluye conversational_text_response, un followup_question y refined_search (una o más búsquedas sugeridas). El orden de visualización recomendado es el siguiente:
      1. conversational_text_response
      2. Sugerencias de refined_search: Se ordenan y clasifican, por lo que es importante mostrarlas en el mismo orden que la respuesta.
      3. Followup_question
    • La respuesta incluye refined_search (una o más búsquedas sugeridas, ordenadas y clasificadas) que se deben usar para recuperar los resultados de la búsqueda con la API de Search principal.
    • Para las interacciones posteriores, envía la respuesta del usuario junto con el conversation_id.

Mostrar sugerencias de búsquedas para productos

Así es como se configura la Búsqueda de Google para mostrar preguntas y sugerencias de productos en el agente de comercio conversacional.

Cuando la API de Conversational devuelve búsquedas de refinedSearch, estas representan excelentes oportunidades para guiar al usuario final hacia productos relevantes. Esto es especialmente valioso para la categoría 4 (búsquedas de respuestas de LLM) y la categoría 5 (INTENT_REFINEMENT).

Recomendación

  • Mostrar: Presenta las principales búsquedas N (de 1 a 3, según las pruebas sobre la cantidad ideal para tu interfaz web) refinedSearch a tu usuario.
  • Mecanismo: Estas búsquedas sugeridas deben ejecutarse a través de la API de Search principal (SearchService.Search) en segundo plano o cuando el usuario interactúa con ellas.
  • Presentación: Muestra los resultados como carruseles interactivos o tarjetas en las que se puede hacer clic, lo que permite que el usuario navegue por categorías de productos relacionadas o elementos específicos. Esto proporciona valor inmediato y ayuda a cerrar la brecha entre la interacción conversacional y el descubrimiento de productos.

Solicitud a la API de búsqueda:

Consulta de seguimiento

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

Eventos que se envían a Vertex AI Search for Commerce

Es importante atribuir con precisión las búsquedas a las interacciones conversacionales y usar todas las capacidades de análisis en Vertex AI Search para comercio electrónico con el etiquetado de eventos adecuado:

  1. Recupera conversation_id. Cuando realizas una llamada a la API de conversationalSearch, se devuelve el objeto ConversationalSearchResponse.conversation_id.
  2. Etiqueta eventos de usuario. En los casos en que la respuesta conversacional genere una búsqueda, por ejemplo, cuando se muestra una sugerencia de refined_search en la que el usuario final hace clic o si tu sistema ejecuta automáticamente una búsqueda basada en la búsqueda refinada, debes etiquetar ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id que se recibió en el ConversationalSearchResponse.

Si etiquetas correctamente UserEvent.conversation_id, tus estadísticas podrán atribuir con precisión las búsquedas a las interacciones conversacionales anteriores, lo que proporcionará estadísticas valiosas sobre el comportamiento del usuario y las rutas de conversión.

Continúa la conversación

En esta sección, se describe cómo la API de Conversational mantiene las sesiones del agente de comercio conversacional y cómo estas continúan en este paso final.

La API de Conversational usa un conversation_id para administrar las conversaciones en curso. Para garantizar la coherencia entre las respuestas del LLM y los resultados de la búsqueda, las solicitudes Conversational API posteriores deben incluir SearchParams que reflejen la configuración de las llamadas principales a la API de Search.

Control de sesiones

  • Sigue estos pasos para iniciar una conversación nueva:
    • Descripción: Para comenzar una conversación nueva, el cliente omite el conversationId de la solicitud a la API.
    • Cuándo iniciar una conversación nueva: Un cliente querrá iniciar una conversación nueva (y, así, obtener un conversationId nuevo de la respuesta de la API) en varias situaciones comunes de la experiencia del usuario:
      • Pestaña o sesión nuevas: Cuando un cliente abre tu sitio en una pestaña del navegador nueva o inicia una sesión completamente nueva
      • Nueva búsqueda original: En algunos diseños de UX, si un cliente ingresa una búsqueda nueva no relacionada, puedes optar por reiniciar el flujo de conversación para garantizar el contexto más pertinente.
      • Botón para reiniciar la conversación: Si tu interfaz web proporciona un botón explícito para Iniciar un chat nuevo o Restablecer la conversación, hacer clic en él activará una nueva sesión de conversación.
    • Integración de la API de Conversational: La respuesta de la API incluye un nuevo conversationId que se usa para solicitudes posteriores.
  • Continúa la conversación:
    • Descripción: Conversational API devuelve un conversation_id como parte de la respuesta de la API. Este ID se debe enviar en las solicitudes de seguimiento para continuar con la misma conversación. Esto ayuda a garantizar que el agente de Conversational Commerce responda a las preguntas del usuario en función del historial de conversaciones de esa sesión, lo que abarca el query del usuario final, el conversational_text_response y el followup_question.
    • Integración de la API de conversación: El cliente pasa el conversation_id de la respuesta anterior en el ConversationalSearchRequest.
  • Asegúrate de que los resultados de la búsqueda sean coherentes:
    • Descripción: Para garantizar que las respuestas del LLM sean coherentes con los resultados de la búsqueda que se muestran al usuario, el cliente debe usar searchParams en la solicitud de Conversational API. Estos parámetros de búsqueda deben tener la misma configuración (por ejemplo, filtros y orden de clasificación) que las llamadas a Search API realizadas para recuperar los resultados de los productos.
    • Integración de la API de Conversational: El objeto searchParams dentro de ConversationalSearchRequest debe completarse de forma idéntica al objeto SearchRequest que se usa para la búsqueda de productos principal.

Envía una solicitud a Vertex AI Search for Commerce

Puedes recuperar el conversation_id del almacenamiento de sesión. La solicitud debe incluir el nuevo query del cliente, que podría ser una respuesta a la pregunta de la respuesta anterior. La solicitud también debe incluir el refined_search.query más reciente de la respuesta anterior si el usuario final está actuando en función de una búsqueda refinada. De lo contrario, debe incluir una búsqueda completamente nueva y no relacionada, y el conversationId. Recuerda que siempre debes incluir searchParams coherentes.

  • Situación 1: Barra de búsqueda única y conversación persistente: Si tu interfaz de búsqueda tiene solo una barra de búsqueda principal o una ventana de conversación persistente, no restablecerás el conversationId, incluso si el usuario final escribe una búsqueda nueva que parece no estar relacionada. El sistema usa el historial de conversación existente (vinculado al conversationId) para proporcionar respuestas pertinentes según el contexto.
  • Situación 2: Ventana de conversación y ventana de búsqueda separadas: Si tu interfaz de búsqueda incluye una ventana de chat conversacional distinta y una barra de búsqueda estándar independiente (como un cuadro de búsqueda en todo el sitio), ingresar una nueva búsqueda en la barra de búsqueda estándar podría indicar de forma implícita la intención de iniciar una búsqueda nueva no relacionada, lo que podría provocar que se restablezca el conversationId para esa acción de búsqueda específica. Sin embargo, dentro de la ventana de conversación dedicada, siempre se debe mantener el conversationId para garantizar la continuidad.

En última instancia, la decisión de cuándo reutilizar o restablecer el conversationId es una elección de diseño para optimizar la experiencia conversacional de tus clientes.

Método y extremo HTTP (igual que la búsqueda inicial)

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

Solicitud a la API conversacional:

Consulta de seguimiento

{
  "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\")"
  }
}

Respuesta de la API conversacional:

Respuesta de seguimiento

{
  "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"
}

Ejemplos de un usuario final que sigue recibiendo preguntas:

  • Pregunta del usuario: Ayúdame a planificar una fiesta.
  • Respuesta del sistema: ¿Qué tipo de fiesta estás planeando?
  • Respuesta del usuario: Una fiesta de cumpleaños.

Qué deben hacer los minoristas con la respuesta

La forma de renderizar los campos es similar a la respuesta inicial, pero ten en cuenta los cambios que reflejan la conversación continua:

  • refined_search: Este campo contiene las búsquedas actualizadas que incorporan la entrada más reciente del usuario final. Debes actualizar la consola del cliente para que coincida con la búsqueda actual (por ejemplo, mostrar que la búsqueda visible para el usuario cambió de "decoraciones" a "decoraciones para fiesta de cumpleaños" o "artículos para fiesta de cumpleaños"). Las búsquedas refinadas se pueden usar para llamar a la API de Search principal (SearchService.Search) o también se pueden mostrar al usuario final como sugerencias.
  • conversational_text_response: Muestra la nueva respuesta de texto generada por IA que es pertinente para el turno más reciente.
  • followup_question: Si la conversación debe continuar para una mayor definición, se proporciona un nuevo followup_question.

Eventos que se envían a Vertex AI Search for Commerce

El etiquetado de eventos es importante para atribuir con precisión las búsquedas a las interacciones conversacionales y para usar las capacidades de Analytics en Vertex AI Search para el comercio.

El proceso de etiquetado de eventos consta de dos pasos:

  1. Recupera conversation_id. Cuando realizas una llamada a la API de conversationalSearch, se devuelve el objeto ConversationalSearchResponse.conversation_id.
  2. Etiqueta eventos de usuario. En los casos en que la respuesta conversacional genere una búsqueda, por ejemplo, cuando se muestra una sugerencia de refined_search, o si tu sistema ejecuta automáticamente una búsqueda basada en la búsqueda refinada, debes etiquetar ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id que se recibió en el ConversationalSearchResponse.

Si etiquetas correctamente UserEvent.conversation_id, tus estadísticas podrán atribuir con precisión las búsquedas a las interacciones conversacionales precedentes, lo que proporcionará estadísticas valiosas sobre el comportamiento del usuario final y las rutas de conversión.

Integra el agente con el filtrado de productos conversacional

En esta guía, se describe cómo realizar la integración con la API de Conversational y el filtrado de productos conversacional para proporcionar una experiencia de compra potenciada por IA. Cuando conversationalFilteringSpec.mode se establece en ENABLED, tu sistema puede realizar la transición directamente entre las interacciones conversacionales abiertas y el filtrado guiado de productos, lo que ofrece un recorrido del usuario muy refinado.

Comprende la interacción

Cuando se habilitan el agente de comercio conversacional y el filtro de productos conversacional, el sistema aprovecha las fortalezas de cada uno. El agente de Comercio conversacional maneja consultas amplias, proporciona respuestas generadas por IA y refina las intenciones iniciales, mientras que el filtro de productos conversacional guía a los usuarios a través de selecciones específicas de atributos de productos con un modelo de interacción simplificado basado en chips o tarjetas.

El punto de interacción y posible transición entre estos dos modos se produce cuando la clasificación de la API de Conversational Commerce conduce a una búsqueda orientada a productos, específicamente SIMPLE_PRODUCT_SEARCH. En este punto, la API puede proporcionar una búsqueda directa o, si la intención del usuario se puede definir mejor, activa un flujo de filtrado guiado a través del filtrado de productos conversacional.

Un principio clave de esta integración es que la API de Conversational Commerce controla todas las entradas de texto libre, mientras que el filtrado de productos conversacional controla los clics en las respuestas sugeridas que aparecen como chips.

Envía la consulta del usuario

Ejemplo de entrada del usuario: Ayúdame a planificar una fiesta

Para habilitar el agente de comercio conversacional y el filtro de productos conversacional, asegúrate de que tu ConversationalSearchRequest incluya esta configuración:

Solicitud a la API de 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
  }
}

Las configuraciones clave son las siguientes:

  • Conversational_filtering_mode: ENABLED: Si configuras este campo como ENABLED en tu objeto conversationalFilteringSpec, le indicas a la API que tu sistema puede controlar el filtrado de productos conversacional, lo que permite que la API proporcione respuestas relevantes específicas para el filtrado.

Respuesta inicial: Refinamiento del intent

El campo userQueryTypes sigue siendo fundamental para comprender la intención del usuario. En el caso de una búsqueda amplia inicial, como Ayúdame a planificar una fiesta, es probable que la API la clasifique como INTENT_REFINEMENT si no se identifica de inmediato una búsqueda de producto más específica.

Respuesta de Google

Respuesta de la API de 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"
}

Acción

  1. Muestra los conversationalTextResponse.
  2. Presenta las sugerencias de refinedSearch como chips en los que se puede hacer clic para Decoraciones y Snacks. Como alternativa, puedes llamar a la API de Commerce Search en paralelo con las búsquedas de refined_search para mostrar resultados de productos relevantes, como Decoraciones, Snacks en un carrusel, junto con el intercambio conversacional.
  3. Mostrar el followupQuestion: ¿Qué tipo de fiesta estás planeando?
  4. Permite que el usuario ingrese texto de formato libre para avanzar en la conversación.

Etiquetado y estadísticas de eventos

Para garantizar la precisión de las estadísticas y la atribución de la interacción conversacional inicial, haz lo siguiente:

  • Recupera conversation_id. Captura el conversation_id del ConversationalSearchResponse. Este ID es fundamental para vincular todas las acciones posteriores a esta sesión de conversación específica.
  • Etiqueta eventos de usuario. Si la respuesta conversacional genera una búsqueda, por ejemplo, si tu sistema ejecuta automáticamente una búsqueda basada en una búsqueda de refined_search, o si el usuario hace clic en una sugerencia de refined_search, debes etiquetar ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id.

Consulta de seguimiento

Cuando el usuario responde a followupQuestion, la conversación se define mejor.

Ejemplo de entrada del usuario: Una fiesta de cumpleaños

Refinamiento de la intención | Fragmentos de código

Solicitud a la API de Conversational Commerce: Consulta de seguimiento

{
  "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"
  }
}

Respuesta de la API de Conversational Commerce: Consulta de seguimiento

{
  "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"
}

Acción

  1. Al igual que con la respuesta inicial, actualiza la interfaz web con las nuevas sugerencias de conversationalTextResponse, refinedSearch y followupQuestion.
  2. Continuar el flujo de la conversación y solicitar más detalles

Etiquetado y estadísticas de eventos

Cuando el usuario continúa la conversación, sucede lo siguiente:

  • Recupera conversation_id. Asegúrate de que el conversation_id del ConversationalSearchResponse anterior se pase al ConversationalSearchRequest actual.
  • Etiqueta eventos de usuario. Si la respuesta conversacional genera una nueva búsqueda, por ejemplo, porque el usuario hizo clic en una sugerencia de refined_search o porque tu sistema realizó una llamada de búsqueda paralela, etiqueta ese evento de usuario de búsqueda posterior (UserEvent) con el mismo conversation_id. Esto ayuda a hacer un seguimiento del recorrido conversacional de varios turnos.

Transición al filtrado de productos conversacional

A medida que la conversación se vuelve más específica, el sistema podría clasificar la intención como SIMPLE_PRODUCT_SEARCH y, si es adecuado, activar el filtrado de productos conversacional.

Ejemplo de entrada del usuario: Tema de princesas

Solicitud a la API de Conversational Commerce: Consulta de seguimiento

{
  "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"
  }
}

Cuando una búsqueda se clasifica como SIMPLE_PRODUCT_SEARCH, hay dos posibles respuestas de la API, según si se activa el filtro de productos conversacional. La diferencia clave radica en la presencia y el contenido del campo conversationalFilteringResult.

Resultado 1: Se activa el filtro

Esto ocurre cuando la búsqueda es lo suficientemente general como para que se pueda definir mejor con atributos del producto. La respuesta incluye conversationalFilteringResult, que tu interfaz web debe priorizar.

Respuesta de la API de Conversational Commerce: Transición al filtrado de productos: 

{
  "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"
}

Acción

Ahora, la búsqueda se clasificó como SIMPLE_PRODUCT_SEARCH. En este caso, se activa el filtrado de productos conversacional. Sin embargo, es posible que no active el filtro de productos conversacional.

  • Prioriza la interfaz web de filtrado de productos conversacional:Cuando se completa conversationalFilteringResult, indica que ingresaste al modo de filtrado de productos. Tu interfaz web debe destacar el followupQuestion, que aparece en la interfaz de usuario como algo similar a ¿Qué tipo específico de decoración de princesa buscas?, y el suggestedAnswers, como botones en los que se puede hacer clic para Globos, serpentinas y manteles.
  • Mostrar resultados de productos: Llama de inmediato a la API de Retail Search con la búsqueda refined_search.query (decoraciones de cumpleaños de princesas) para mostrar los resultados iniciales de los productos junto con las opciones de filtrado.
  • Práctica recomendada para la experiencia del usuario: Debe haber una sola barra de entrada de texto libre persistente para toda la experiencia. Esta barra permanece activa en todo momento, incluso durante un flujo de filtrado de productos conversacional. Cuando el conversationalFilteringResult está activo y muestras respuestas sugeridas como chips en los que se puede hacer clic, los usuarios tienen dos opciones claras:
    • Haz clic en una respuesta sugerida para continuar con el flujo de filtrado.
    • Inicia un nuevo turno de conversación escribiendo una nueva búsqueda en la barra de texto activa. Esta nueva entrada siempre activa una nueva llamada a la API de Conversational Commerce, lo que finaliza de manera efectiva el flujo de filtrado actual.

Resultado 2: No se activa ningún filtro

Si la búsqueda ya es lo suficientemente específica o no se presta a un filtrado adicional, la respuesta no incluye el campo conversationalFilteringResult. En este caso, debes realizar una búsqueda estándar.

Acción

  • Trata la interacción como el final del flujo de conversación y usa la búsqueda refined_search para llamar a la API de Retail Search y mostrar una página de resultados de productos estándar.

Etiquetado y estadísticas de eventos

Cuando la conversación pasa al filtrado de productos, sucede lo siguiente:

  • Recupera conversation_id. Sigue usando el mismo conversation_id.
  • Etiqueta eventos de usuario. Si la transición conduce a una búsqueda inmediata, etiqueta ese UserEvent con el conversation_id. Es importante destacar que, cuando el usuario interactúa con el suggestedAnswers, por ejemplo, cuando un usuario final hace clic en Globos, esta acción también debe activar un UserEvent, como un evento filter o un nuevo evento search, que esté etiquetado con el mismo conversation_id. Esto permite la atribución de las acciones de filtrado dentro del flujo de conversación.

Continuar con el filtrado de productos conversacional

Cuando el usuario selecciona un suggestedAnswer, envía un nuevo ConversationalSearchRequest.

Ejemplo de entrada del usuario (clic en una respuesta sugerida): Globos

Búsqueda simple de productos | Fragmentos de código

Solicitud a la API de Conversational Commerce: Continúa filtrando 

{
  "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"
  }
}

Respuesta de la API de Conversational Commerce: Continue filtering 

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

Acción

La API responde con una consulta SIMPLE_PRODUCT_SEARCH, pero sin el campo conversationalFilteringResult, lo que indica que finalizó el flujo de filtrado guiado.

  • Usa la búsqueda final refinedSearch (globos de cumpleaños de princesa) para realizar una llamada directa a la API de Retail Search.
  • Mostrar los resultados del producto final al usuario En este punto, la conversación puede finalizar o el usuario puede ingresar una nueva búsqueda para iniciar un nuevo turno.

Etiquetado y estadísticas de eventos

Para cada paso del proceso de filtrado de productos, haz lo siguiente:

  • Recupera conversation_id. Siempre usa el mismo conversation_id para todas las solicitudes dentro de la sesión de filtrado.
  • Etiqueta eventos de usuario. Cada interacción del usuario con un suggestedAnswer, como un clic, debe activar un UserEvent pertinente, como un evento filter o un evento search nuevo si se forma una nueva búsqueda. Este UserEvent debe etiquetarse con conversation_id para hacer un seguimiento preciso del recorrido de filtrado y su impacto en la conversión.

Recomendaciones de la interfaz de usuario y opciones de diseño

La interacción entre el agente conversacional de comercio y el filtrado de productos conversacional ofrece una flexibilidad significativa. Estas son algunas consideraciones clave de UX para crear una experiencia fluida e intuitiva:

  • Barra de entrada única: Solo debe haber una barra de entrada de texto libre para toda la experiencia. No hay una barra de entrada independiente y exclusiva para el Filtro de productos conversacional. Esto simplifica la interfaz de usuario y mantiene la interacción coherente.
  • Transiciones fluidas: Diseña tu interfaz web para que las transiciones entre las respuestas conversacionales, las búsquedas sugeridas y las opciones de filtrado se sientan naturales e intuitivas.
  • Orientación clara: Usa indicadores visuales, como estilos de botones distintos para las respuestas sugeridas en lugar de entradas generales, y proporciona instrucciones claras para guiar al usuario sobre cómo interactuar en cada etapa.
  • Equilibrio del control: El usuario siempre debe sentir que controla la dirección de la conversación.
    • Filtrado vs. formato libre: La única barra de entrada de texto libre permanece activa en todo momento. Esto le brinda al usuario una opción constante: puede hacer clic en una respuesta sugerida para seguir definiendo su búsqueda o escribir una nueva consulta en la barra de texto para iniciar un nuevo turno de conversación. Este diseño garantiza que, incluso durante un flujo de filtrado, el usuario pueda cambiar a un tema diferente si cambian sus necesidades.
    • Opción de restablecimiento: Proporciona una opción clara para Iniciar una conversación nueva o Restablecer filtros para permitir que los usuarios reinicien su proceso de búsqueda o filtrado.

  • Persistencia visual: Incluso cuando se realiza la transición al filtrado de productos, mantener el historial de conversación dentro de la ventana de chat, como mostrar preguntas y respuestas anteriores, puede mejorar el contexto y la experiencia del usuario.

Consideraciones y prácticas recomendadas adicionales

Cuando implementes la interfaz de tu agente de comercio conversacional, debes tener en cuenta las siguientes consideraciones y prácticas recomendadas adicionales:

  • Coherencia del ID de visitante: Ayuda a garantizar que se envíe un visitor_id único de forma coherente con cada solicitud para un usuario final determinado. Esto es fundamental para la personalización precisa y el entrenamiento de modelos. Lo ideal es que este identificador siga siendo coherente para un usuario final en todas las sesiones y los estados de acceso o salida.
  • Administración de ramas: Si bien default_branch es común, asegúrate de usar el ID de rama correcto si tu catálogo de productos está estructurado con varias ramas.
  • Interacción con la API de búsqueda: Para SIMPLE_PRODUCT_SEARCH y cualquier caso en el que se proporcione refined_search, recuerda hacer una llamada independiente a la API de búsqueda principal (SearchService.Search) con el query del campo refined_search o la búsqueda original para obtener las fichas de productos reales. La API de Conversational se enfoca principalmente en la experiencia conversacional y la comprensión de la intención del usuario, en lugar de mostrar directamente resultados de productos.
  • Diseño de la interfaz de usuario: Diseña tu interfaz web para presentar claramente las opciones de conversational_text_response, followup_question y refined_search de una manera intuitiva para guiar al usuario.

¿Qué sigue?

Para obtener más recursos de asistencia, consulta las Preguntas frecuentes sobre las funciones de conversación.