Guide du développeur d'agents de commerce conversationnel

Ce guide explique comment intégrer l'API Conversationnelle pour offrir à vos clients des expériences de chat dynamiques optimisées par l'IA. En comprenant les différents types de requêtes et en exploitant les réponses de l'API, vous pouvez proposer des recherches de produits pertinentes, répondre aux questions de vos clients et guider vos utilisateurs finaux tout au long de leur parcours d'achat.

Le conversationalFilteringMode de l'API Conversationnelle permet de distinguer clairement l'agent de commerce conversationnel du filtrage conversationnel des produits.

Configuration

L'API Conversational est compatible avec la fonctionnalité d'agent de commerce conversationnel :

L'API Conversational permet une expérience de chat dans laquelle vos utilisateurs envoient des requêtes et le système renvoie une réponse textuelle, des types de requêtes classés et des options de recherche affinées potentielles.

Cette API fonctionne comme un service de streaming, ce qui permet de détecter rapidement l'intention de la requête. Les interactions ultérieures dans la conversation nécessitent l'ajout d'un conversation_id.

Pour renvoyer des résultats de recherche, l'ancienne API Retail doit être appelée en parallèle de l'API Conversational.

Envoyer une requête de l'utilisateur final

Cette section explique comment lancer une expérience d'agent de commerce conversationnel. Par exemple, votre utilisateur peut saisir Aide-moi à organiser une fête dans le champ de recherche.

Envoyer une requête à Vertex AI Search pour le commerce

Il existe deux points de terminaison d'API différents :

  1. L'API Conversationnelle doit être utilisée pour récupérer l'expérience conversationnelle.
  2. L'API Search principale doit être utilisée pour récupérer les résultats de recherche.

Point de terminaison 1 : requête de l'API Conversationnelle

  • Vous devez créer une demande d'agent Conversational Commerce en définissant l'entrée de votre utilisateur comme requête.
  • La requête doit être envoyée en tant que requête HTTP POST au point de terminaison projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Méthode HTTP et point de terminaison

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

Requête API conversationnelle :

Requête initiale

{
  "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 : nom de ressource de l'emplacement (par exemple, projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Il s'agit d'un paramètre de chemin d'accès obligatoire.
  • query : requête de recherche brute de votre utilisateur. Ce champ est obligatoire.
  • branch : nom de la ressource de branche, par exemple projects/P/locations/L/catalogs/C/branches/B. Si ce paramètre n'est pas défini, default_branch est utilisé. Ce champ est obligatoire.
  • visitorId : identifiant unique permettant d'effectuer le suivi des visiteurs. Ce champ est obligatoire.
  • conversationId : ID unique permettant de suivre les sessions de conversation. Pour la première demande dans une nouvelle conversation, ce champ doit être vide. Pour les requêtes suivantes dans la même conversation, il doit être défini sur le conversation_id reçu dans le ConversationalSearchResponse précédent.
  • searchParams : (facultatif) paramètres standards de la recherche, tels que filter, canonicalFilter, sortBy et boostSpec. Il est essentiel que ces paramètres reflètent la configuration utilisée dans vos appels d'API Search principaux pour garantir la cohérence entre les réponses du LLM et les résultats de recherche de produits affichés.
  • userInfo : (facultatif) Informations sur l'utilisateur pour une personnalisation améliorée. Peut inclure userId, user_agent et direct_user_request (booléen).
  • conversationalFilteringSpec : (facultatif) spécifie le mode de filtrage conversationnel. Si cette valeur n'est pas définie, la valeur par défaut est "DISABLED" (DÉSACTIVÉ).

    mode : intégrez l'API Conversationnelle à l'aide de l'un de ces trois modes pour contrôler le filtrage des produits conversationnels :

    • DISABLED : dans ce mode, le client n'implémente que la recherche d'agents de commerce conversationnel. Il s'agit du mode préféré pour ce guide d'implémentation sur la recherche d'agents de commerce conversationnel.

      • Exemple de requête 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
        }

      Exemple de réponse de l'API

              user_query_types: "SIMPLE_PRODUCT_SEARCH"
        conversation_id: "479fd093-c701-4899-bcc3-9e711233bdf9"
        refined_search {
          query: "monster energy drinks"
        }
    • ENABLED : dans ce mode, le client implémente toutes les fonctionnalités conversationnelles, y compris la recherche d'agents de commerce conversationnel et le filtrage conversationnel des produits.

      • Consultez le guide supplémentaire sur l'intégration des produits conversationnels.

      Exemple de requête 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
        }

      Exemple de réponse de l'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 cette option est sélectionnée, le client implémente uniquement le filtrage conversationnel des produits. Lorsque ce mode est sélectionné, l'utilisateur ne bénéficie que du filtrage conversationnel des produits, sans génération de réponse LLM, de classification de requête ni de suggestions de requêtes de recherche.

      • Pour en savoir plus, consultez le guide du développeur sur les filtres de produits conversationnels.

Point de terminaison 2 : requête de l'API Core Search

Il existe deux approches principales pour afficher les résultats de recherche dans votre interface Web.

Option 1 : Toujours afficher les résultats de recherche

Si votre conception de l'expérience utilisateur exige que les résultats de recherche soient toujours affichés, quelle que soit la sortie conversationnelle (par exemple, dans une zone de résultats de recherche dédiée à côté du chat), envoyez la requête d'origine de l'utilisateur à l'API Product Search principale avec votre appel à l'API Conversational. Cela permet de s'assurer que les fiches produit sont immédiatement disponibles.

Option 2 : Afficher les résultats de recherche en fonction du résultat conversationnel

Si la conception de votre expérience utilisateur est plus dynamique et que vous ne souhaitez afficher les résultats de recherche qu'en fonction de la réponse de l'API Conversationnelle (par exemple, uniquement pour les requêtes SIMPLE_PRODUCT_SEARCH ou chaque fois que des suggestions refined_search sont fournies), attendez la réponse de l'API Conversationnelle avant d'envoyer des requêtes à l'API Product Search principale. S'il y a une réponse, utilisez la requête refined_search fournie pour récupérer les résultats des produits.

Quelle que soit l'option d'interface utilisateur choisie, vous pouvez appeler l'API Retail lorsque vous avez besoin d'extraire les résultats des produits. Pour en savoir plus, consultez Comprendre les types de requêtes et les actions des marchands.

Méthode HTTP et point de terminaison

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

Requête de l'API Search du produit principal :

Requête initiale

    {
      "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 (obligatoire) : nom de la ressource de la configuration de diffusion Retail Search ou de l'emplacement existant. Exemple : projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
  • query : obligatoire. Requête de recherche. Il peut s'agir de la saisie brute de votre utilisateur, comme Aide-moi à organiser une fête, ou d'une refinedSearch.query plus optimisée (comme fournitures pour organiser une fête, décorations) obtenue à partir de la réponse de l'API Conversational Commerce.
  • visitorId : obligatoire. Identifiant unique permettant d'effectuer le suivi des visiteurs. Cette valeur doit être cohérente avec le visitorId envoyé à l'API Conversational Commerce pour le même utilisateur final.
  • branch (obligatoire) : nom de la ressource de branche, tel que projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
  • pageSize (facultatif) : nombre maximal de produits à renvoyer.
  • filter (facultatif) : utilisé pour filtrer les résultats de recherche. C'est ici que vous appliquerez les filtres qui reflètent ce que vous envoyez dans `searchParams` à l'API Conversational Commerce pour assurer la cohérence.
  • orderBy (facultatif) : spécifie l'ordre dans lequel les produits sont renvoyés (par pertinence ou par prix, par exemple).
  • userInfo (facultatif) : informations utilisateur pour la personnalisation. Elles doivent être cohérentes avec l'appel de l'API Conversational Commerce.
  • searchMode (facultatif) : définit le comportement de recherche. PRODUCT_SEARCH est courant pour les requêtes générales sur les produits.

Comprendre la réponse

Cet exemple de code illustre une réponse de l'API Conversational Commerce.

La réponse de l'API (ConversationalSearchResponse) inclut query_types, conversational_text_response (le cas échéant), les options refined_search et potentiellement un followup_question ou un conversational_filtering_result. Le conversation_id est essentiel pour poursuivre la session.

Réponse de Vertex AI Search pour le commerce

Cet exemple de code illustre une réponse de l'API Conversational :

Réponse initiale

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

Que doivent faire les marchands avec la réponse (général)

Affichez les champs suivants de la réponse :

  • user_query_types : ce champ fournit la ou les classifications de l'intention de votre utilisateur. Pour en savoir plus sur les actions détaillées en fonction de ces types, consultez Comprendre les types de requêtes et les actions des marchands.
  • conversation_id : vous pouvez stocker cet ID unique dans le stockage de session de votre navigateur ou dans un stockage côté client similaire pour maintenir la session de conversation avec le serveur. Cela est essentiel pour faire la distinction entre plusieurs conversations en cours pour un même client. Votre modèle conserve le contexte pour un conversation_id donné. L'envoi d'une nouvelle conversation_id démarre une nouvelle session. Nous vous recommandons de définir la durée de votre session, par exemple 30 minutes d'inactivité.
  • refined_search : liste des requêtes de recherche affinées proposées pour récupérer les résultats de recherche pertinents. Pour SIMPLE_PRODUCT_SEARCH, il s'agit toujours d'une seule requête. Pour les autres requêtes visant à obtenir une réponse LLM, il s'agit d'un ou plusieurs résultats. Les requêtes refined_search peuvent être utilisées pour les appels à l'API Search principale (SearchService.Search) ou peuvent également être affichées à l'utilisateur sous forme de suggestions.
  • conversational_text_response : affichez ce texte à l'utilisateur comme réponse principale générée par l'IA à sa requête.
  • followup_question : facultatif. L'état followup_question s'affiche.
  • state : ce champ indique l'état de la génération de la réponse ("STREAMING" ou "SUCCEEDED"). Vous pouvez l'utiliser pour obtenir des commentaires sur l'expérience utilisateur, par exemple en affichant un indicateur de chargement jusqu'à "SUCCEEDED". Nous y reviendrons plus en détail dans la section suivante.

Comprendre l'API Streaming

L'API Conversational Commerce fonctionne comme une API de streaming. Cela signifie que votre utilisateur reçoit des parties de la réponse dans plusieurs blocs plutôt que dans une seule charge utile complète.

Le premier bloc de la réponse inclut les requêtes query_types et refined_search, et son state est indiqué comme STREAMING. Cette détection précoce de l'intention et la disponibilité immédiate des affinements de recherche permettent à votre modèle de prendre rapidement des décisions sur la façon de traiter la requête de votre utilisateur et de gérer son expérience en termes de latence des réponses du LLM :

  • Pour les types de requêtes qui n'attendent pas de réponse textuelle conversationnelle, comme SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT :
    • Comme query_types se trouve dans le premier bloc, votre système sait immédiatement qu'aucune réponse de LLM n'est à venir. Vous pouvez poursuivre le traitement prédéfini pour ces types, par exemple en affichant un message statique ou en redirigeant l'utilisateur vers l'assistance, sans attendre d'autres résultats conversationnels.
    • Plus précisément pour SIMPLE_PRODUCT_SEARCH, votre système peut immédiatement effectuer un appel direct à l'API Search principale à l'aide de la requête refined_search reçue dans le premier bloc. Cela permet de s'assurer que les résultats de recherche s'affichent avec un délai minimal, conformément aux SLA habituels de l'expérience de recherche.
  • Pour les types de requêtes qui attendent une réponse textuelle conversationnelle, comme INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON et BEST_PRODUCT :
    • Vous recevez les requêtes query_types et refined_search dans le bloc initial. Vous pouvez immédiatement lancer un appel parallèle à l'API Search principale à l'aide de ces requêtes refined_search pour commencer à charger les résultats des produits.
    • Les blocs suivants sont diffusés en streaming et contiennent différentes sections de la réponse textuelle conversationnelle. Pendant ce temps, l'état state reste "STREAMING".
    • Enfin, le dernier bloc inclut la réponse textuelle complète de la conversation, et son state passe à "COMPLETED".
    • Cette approche de streaming permet une expérience utilisateur fluide, où les résultats de recherche peuvent commencer à se charger pendant que le résumé de l'IA est généré. Vous pouvez choisir d'afficher un indicateur de chargement pour la réponse conversationnelle ou de la présenter une fois qu'elle est entièrement diffusée.

Comprendre les types de requêtes et les actions des marchands

Le champ query_types de la réponse est une liste indiquant la ou les classifications de l'intention de votre utilisateur. Votre système doit les gérer comme suit. Notez que conversational_text_response fait référence à la réponse en langage naturel générée par l'IA à partir de l'API.

L'agent Conversational Commerce utilise des catégories de requêtes de recherche pour déterminer si une réponse basée sur un LLM est générée et comment les requêtes des utilisateurs finaux sont traitées par les API Conversational et Search dans les scénarios suivants :

Catégories Classifications des requêtes
1. Requêtes non pertinentes qui ne nécessitent pas de réponse du LLM
  • QUERY_TYPE_UNSPECIFIED : type de requête non spécifié.
  • RETAIL_IRRELEVANT : requêtes non pertinentes pour le domaine du commerce, par exemple une requête contradictoire (comme comment fabriquer une bombe), une requête bavarde (comme comment allez-vous) ou une requête de jailbreak (comme écrire un poème).
  • BLOCKLISTED : requêtes explicitement bloquées par les clients commerciaux (par exemple, Quels sont les effets secondaires de l'Advil ?).
2. Demandes d'assistance et d'informations
  • ORDER_SUPPORT : requête auxiliaire ou d'assistance (par exemple, Suivre ma commande, état de la commande 12345).
  • DEALS_AND_COUPONS : requêtes liées aux offres, aux promotions, aux offres de produits et aux remises (par exemple, Y a-t-il des offres pour Thanksgiving ?).
  • STORE_RELEVANT : requêtes liées aux magasins, y compris les horaires d'ouverture et la disponibilité des produits (par exemple, Avez-vous du lait en stock ?).
  • RETAIL_SUPPORT : requêtes liées aux achats, y compris les modes de paiement (Quels sont les modes de paiement acceptés ?).
3. Recherches par mots clés ne nécessitant pas de LLM

Requête API conversationnelle :

Requête initiale

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

Réponse de l'API conversationnelle :

Réponse initiale

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

Requête API Search :

Requête complémentaire

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "monster energy drinks",
  "visitorId": "test"
}
  • SIMPLE_PRODUCT_SEARCH : recherche de produits de base, comme robe rouge ou montre-moi des Monster Energy
4. Requêtes de recherche de réponses LLM

Requête API conversationnelle :

Requête initiale

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

Réponse de l'API conversationnelle :

Réponse initiale

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

Requête API Search :

Requête complémentaire

{
  "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search",
  "query": "1% milk",
  "visitorId": "test"
}
  • PRODUCT_DETAILS : votre utilisateur recherche des informations et des caractéristiques sur un produit, par exemple montre-moi les caractéristiques de [nom du produit], quelle est la teneur en protéines du lait à 2 % ?
  • PRODUCT_COMPARISON : comparaison de produits, par exemple compare [nom du produit] et [nom du produit], compare le lait à 1 % et le lait à 2 %.
  • BEST_PRODUCT : requêtes correspondant le mieux au modèle, comme Quel est le cookie le plus sain ? Quelle est la meilleure marque de lait ?
5. Affiner l'intention

Requête API conversationnelle :

Requête initiale

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

Réponse de l'API conversationnelle :

Réponse initiale

{
  "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 : le type n'est pas clair et une conversation ou une clarification complémentaire peut être nécessaire pour le préciser, par exemple Aide-moi à organiser une fête. Il s'agit souvent de l'intention la plus populaire dans les conversations.

Catégorie 1. Requêtes non pertinentes qui ne nécessitent pas de réponse du LLM

  • QUERY_TYPE_UNSPECIFIED :
    • Aucun conversational_text_response n'est fourni.
    • Action : gérez-le comme un cas par défaut ou d'erreur. Vous pouvez demander à l'utilisateur de fournir des précisions ou l'orienter vers un endroit où il peut obtenir de l'aide générale.
  • RETAIL_IRRELEVANT :
    • Aucun conversational_text_response n'est fourni.
    • Action : gérez cela en affichant un message approprié, tel que Je ne peux pas répondre à cette question ou Je suis un assistant d'achat, comment puis-je vous aider ?, comme défini par la conception de votre application.
  • BLOCKLISTED :
    • Aucun conversational_text_response n'est fourni.
    • Action : gérez la demande conformément à votre règlement concernant la liste de blocage, généralement en affichant un message générique Impossible de traiter cette demande.

Catégorie 2. Demandes d'assistance et d'informations

Pour ces types, l'API ne fournit pas de conversational_text_response direct par défaut, mais vous avez la possibilité de rediriger les utilisateurs vers les liens ou ressources appropriés.

  • ORDER_SUPPORT :
    • Action par défaut : aucune conversational_text_response n'est fournie. Votre interface Web doit afficher un message standard, des liens pertinents ou rediriger la requête vers votre propre API d'assistance ou canal de service client dédié.
  • DEALS_AND_COUPONS :
    • Action par défaut : aucune conversational_text_response n'est fournie. Votre interface Web doit afficher un message standard, des liens pertinents ou rediriger la requête vers votre système d'offres ou de promotions.
  • STORE_RELEVANT :
    • Action par défaut : aucune conversational_text_response n'est fournie. Votre interface Web doit afficher un message standard, des liens pertinents ou rediriger la requête vers votre propre outil de localisation de magasins ou système d'information.
  • RETAIL_SUPPORT :
    • Action par défaut : aucune conversational_text_response n'est fournie. Votre interface Web doit afficher un message standard, des liens pertinents ou rediriger la requête vers votre propre système de questions fréquentes et d'informations.

Catégorie 3. Recherches par mots clés ne nécessitant pas de réponses LLM

  • SIMPLE_PRODUCT_SEARCH :
    • Aucune réponse textuelle conversationnelle n'est générée.
    • Action : la réponse de l'API renvoie toujours une seule requête refined_search. Cette requête affinée sert de terme de recherche suggéré. Appelez directement l'API Search principale (SearchService.Search) et récupérez les résultats de produits pertinents à l'aide de la requête d'origine ou de la requête refined_search. La refined_search.query peut ne pas provenir directement de la saisie de l'utilisateur final actuel, mais peut également être dérivée du contexte de l'historique des discussions. Par exemple, si un utilisateur final a précédemment affiné la requête robe de soirée en robes rouges, la requête affinée peut devenir robe de soirée rouge.
      • Pour les interfaces conversationnelles (comme les chatbots) : il est fortement recommandé d'utiliser le refined_search.query fourni par l'API. Dans un flux conversationnel, les requêtes en langage naturel telles que "peux-tu m'aider à trouver des bananes" sont automatiquement optimisées par l'API en un terme de recherche de produit précis ("bananes"), ce qui permet d'obtenir des résultats de produits plus pertinents.
      • Pour les expériences de recherche principales (comme la page de résultats de recherche) : vous pouvez utiliser le refined_search.query de l'API ou la requête d'origine fournie par l'utilisateur final, car il est plus probable que la requête d'origine soit déjà un terme de recherche de produit précis. Choisissez l'option qui correspond le mieux à votre interface Web et à votre stratégie d'affichage des résultats de recherche.
    • Options d'expérience utilisateur : la conversation n'a pas besoin de se terminer pour les requêtes SIMPLE_PRODUCT_SEARCH. Votre utilisateur peut poursuivre la conversation en transmettant le conversation_id dans les requêtes suivantes.
      • Option A : Mettre fin à l'interface Web conversationnelle : de nombreux marchands choisissent de rediriger l'utilisateur vers une page de résultats de recherche standard lorsqu'un SIMPLE_PRODUCT_SEARCH est détecté, ce qui ferme la fenêtre de chat. Dans ce scénario, si l'utilisateur final saisit une nouvelle requête dans le champ de recherche standard sans le conversation_id précédent, elle est traitée comme une nouvelle conversation distincte et un nouveau conversation_id est émis.
      • Option B : Continuer l'interface Web conversationnelle : les marchands peuvent choisir de laisser la fenêtre de chat ouverte. Cela permet à votre utilisateur de revenir à un mode conversationnel. Le choix entre l'option A et l'option B dépend entièrement de l'expérience utilisateur préférée du marchand.

    Pour attribuer précisément les requêtes de recherche aux interactions conversationnelles et utiliser toutes les fonctionnalités d'analyse dans Vertex AI Search pour le commerce, il est essentiel de taguer correctement les événements :

    1. Récupérer conversation_id Lorsque vous effectuez un appel d'API conversationalSearch, ConversationalSearchResponse.conversation_id est renvoyé.
    2. Taggez les événements utilisateur. Dans les cas où la réponse conversationnelle conduit à une requête de recherche, par exemple si votre système exécute automatiquement une recherche basée sur la requête affinée pour SIMPLE_PRODUCT_SEARCH, vous devez taguer cet événement utilisateur de recherche ultérieur (UserEvent) avec le même conversation_id reçu dans ConversationalSearchResponse.

En taguant correctement UserEvent.conversation_id, vos données analytiques peuvent attribuer précisément les requêtes de recherche aux interactions conversationnelles précédentes. Vous obtenez ainsi des insights précieux sur le comportement de vos utilisateurs et les chemins de conversion.

Catégorie 4. Requêtes de recherche de réponses LLM

Pour ces types de requêtes, l'API génère une conversational_text_response (réponse LLM) et peut également fournir une ou plusieurs requêtes refined_search. La conversation ne se termine pas et l'utilisateur final peut la poursuivre.

  • PRODUCT_DETAILS :
    • Action : conversational_text_response fournit les informations demandées sur le produit. Votre système doit afficher clairement ces informations à l'utilisateur.
    • La réponse inclut également refined_search (une ou plusieurs requêtes de recherche suggérées, classées et ordonnées) qui doivent être utilisées pour récupérer les résultats de recherche à l'aide de l'API Search principale.
  • PRODUCT_COMPARISON :
    • Action : conversational_text_response compare les produits spécifiés. Votre système doit afficher clairement ces informations à l'utilisateur.
    • La réponse inclut refined_search (une ou plusieurs requêtes de recherche suggérées, classées et ordonnées) qui doivent être utilisées pour récupérer les résultats de recherche à l'aide de l'API Search principale.
  • BEST_PRODUCT :
    • Action : le conversational_text_response fournit des recommandations ou des informations sur les produits qui correspondent le mieux à la requête. Votre système devrait afficher ces informations.
    • La réponse inclut refined_search (une ou plusieurs requêtes de recherche suggérées, classées et ordonnées) qui doivent être utilisées pour récupérer les résultats de recherche à l'aide de l'API Search principale.

Catégorie 5. Affinement des intents

  • INTENT_REFINEMENT :
    • Action : la réponse inclut conversational_text_response, followup_question et refined_search (une ou plusieurs requêtes de recherche suggérées). L'ordre d'affichage recommandé est le suivant :
      1. conversational_text_response
      2. Suggestions refined_search : elles sont classées et ordonnées. Il est donc important de les afficher dans le même ordre que dans la réponse.
      3. Followup_question
    • La réponse inclut refined_search (une ou plusieurs requêtes de recherche suggérées, classées et ordonnées) qui doivent être utilisées pour récupérer les résultats de recherche à l'aide de l'API Search principale.
    • Pour les interactions suivantes, envoyez la réponse de l'utilisateur avec le conversation_id.

Afficher les requêtes suggérées pour les produits

Voici comment configurer la recherche Google pour afficher des questions et des suggestions de produits dans l'agent de commerce conversationnel.

Lorsque l'API Conversationnel renvoie des requêtes refinedSearch, celles-ci représentent d'excellentes opportunités pour orienter l'utilisateur final vers des produits pertinents. Cela est particulièrement utile pour la catégorie 4 (requêtes de recherche de réponses LLM) et la catégorie 5 (INTENT_REFINEMENT).

Recommandation

  • Display : présentez à l'utilisateur les N requêtes refinedSearch les plus pertinentes (entre 1 et 3, en attendant de déterminer le nombre idéal pour votre interface Web).
  • Mécanisme : ces requêtes suggérées doivent être exécutées en arrière-plan ou lors d'une interaction utilisateur via l'API Search principale (SearchService.Search).
  • Présentation : affichez les résultats sous forme de carrousels interactifs ou de fiches cliquables, permettant à vos utilisateurs de parcourir des catégories de produits associées ou des articles spécifiques. Cela offre une valeur immédiate et permet de combler le fossé entre l'interaction conversationnelle et la découverte de produits.

Requête API Search :

Requête complémentaire

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

Événements à envoyer à Vertex AI Search pour le commerce

Il est important d'attribuer précisément les requêtes de recherche aux interactions conversationnelles et d'utiliser toutes les fonctionnalités d'analyse dans Vertex AI Search for Commerce en utilisant le taggage d'événements approprié :

  1. Récupérer conversation_id Lorsque vous effectuez un appel d'API conversationalSearch, ConversationalSearchResponse.conversation_id est renvoyé.
  2. Taggez les événements utilisateur. Dans les cas où la réponse conversationnelle conduit à une requête de recherche, par exemple en affichant une suggestion refined_search sur laquelle l'utilisateur final clique, ou si votre système exécute automatiquement une recherche en fonction de la requête affinée, vous devez taguer cet événement utilisateur de recherche ultérieur (UserEvent) avec le même conversation_id reçu dans le ConversationalSearchResponse.

En taguant correctement UserEvent.conversation_id, vos données analytiques peuvent attribuer précisément les requêtes de recherche aux interactions conversationnelles précédentes. Vous obtenez ainsi des insights précieux sur le comportement des utilisateurs et les chemins de conversion.

Continuez la conversation

Cette section explique comment les sessions d'agent de commerce conversationnel sont gérées par l'API Conversational et se poursuivent dans cette dernière étape.

L'API Conversational utilise un conversation_id pour gérer les conversations en cours. Pour assurer la cohérence entre les réponses du LLM et les résultats de recherche, les requêtes Conversational API suivantes doivent inclure SearchParams qui reflètent la configuration des appels de l'API Search principale.

Gestion des sessions

  • Démarrer une conversation :
    • Description : pour démarrer une conversation, le client omet le conversationId de la requête API.
    • Quand démarrer une nouvelle conversation : un client peut vouloir démarrer une nouvelle conversation (et ainsi obtenir un nouveau conversationId dans la réponse de l'API) dans plusieurs scénarios d'expérience utilisateur courants :
      • Nouvel onglet ou nouvelle session : lorsqu'un client ouvre votre site dans un nouvel onglet de navigateur ou démarre une toute nouvelle session.
      • Nouvelle requête d'origine : dans certaines conceptions UX, si un client saisit une nouvelle requête sans rapport, vous pouvez choisir de redémarrer le flux de conversation pour garantir le contexte le plus pertinent.
      • Bouton "Redémarrer la conversation" : si votre interface Web fournit un bouton explicite Démarrer une nouvelle discussion ou Réinitialiser la conversation, le fait de cliquer dessus déclenchera une nouvelle session de conversation.
    • Intégration de l'API conversationnelle : la réponse de l'API inclut un nouveau conversationId qui est utilisé pour les requêtes suivantes.
  • Continuer la conversation :
    • Description : Conversational API renvoie un conversation_id dans la réponse de l'API. Cet ID doit être envoyé dans les demandes de suivi pour poursuivre la même conversation. Cela permet de s'assurer que l'agent de commerce conversationnel répond aux requêtes de vos utilisateurs en fonction de l'historique des conversations de cette session, en couvrant l'query, le conversational_text_response et le followup_question de l'utilisateur final.
    • Intégration de l'API Conversationnelle : le client transmet le conversation_id de la réponse précédente dans le ConversationalSearchRequest.
  • Assurez-vous de la cohérence des résultats de recherche :
    • Description : pour s'assurer que les réponses du LLM sont cohérentes avec les résultats de recherche affichés à l'utilisateur, le client doit utiliser searchParams dans la requête Conversational API. Ces paramètres de recherche doivent avoir la même configuration (filtres, ordre de tri, etc.) que les appels Search API effectués pour récupérer les résultats des produits.
    • Intégration de l'API Conversational : l'objet searchParams dans ConversationalSearchRequest doit être renseigné de la même manière que SearchRequest utilisé pour la recherche de produits principaux.

Envoyer une requête à Vertex AI Search pour le commerce

Vous pouvez récupérer le conversation_id à partir du stockage de session. La requête doit inclure le nouveau query du client, qui peut être une réponse à la question de la réponse précédente. La requête doit également inclure le refined_search.query le plus récent de la réponse précédente si l'utilisateur final agit sur une requête affinée. Sinon, elle doit inclure une requête totalement nouvelle et sans rapport, ainsi que conversationId. N'oubliez pas d'inclure des searchParams cohérents.

  • Scénario 1 : Barre de recherche unique et conversation persistante : si votre interface de recherche ne comporte qu'une seule barre de recherche principale ou une fenêtre de conversation persistante, vous ne réinitialiserez pas conversationId, même si l'utilisateur final saisit une nouvelle requête qui semble sans rapport. Le système utilise l'historique des conversations existant (associé à conversationId) pour fournir des réponses contextuellement pertinentes.
  • Scénario 2 : Fenêtre de conversation et fenêtre de requête distinctes : si votre interface de recherche comporte une fenêtre de chat conversationnel distincte et une barre de requête de recherche standard distincte (comme une barre de recherche à l'échelle du site), la saisie d'une nouvelle requête dans la barre de recherche standard peut signaler implicitement l'intention de lancer une nouvelle recherche sans rapport, ce qui peut entraîner la réinitialisation de conversationId pour cette action de recherche spécifique. Toutefois, dans la fenêtre de conversation dédiée, la conversationId doit toujours être conservée pour assurer la continuité.

En fin de compte, la décision de réutiliser ou de réinitialiser le conversationId est un choix de conception visant à optimiser l'expérience conversationnelle pour vos clients.

Méthode HTTP et point de terminaison (identiques à la requête initiale)

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

Requête API conversationnelle :

Requête complémentaire

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

Réponse de l'API conversationnelle :

Réponse complémentaire

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

Exemples de cas où un utilisateur final continue de recevoir des questions :

  • Question de l'utilisateur : Aide-moi à organiser une fête.
  • Réponse du système : Quel type de fête prévoyez-vous d'organiser ?
  • Réponse de l'utilisateur : Une fête d'anniversaire.

Que doivent faire les marchands avec la réponse ?

La façon d'afficher les champs est semblable à la réponse initiale, mais notez les modifications qui reflètent la poursuite de la conversation :

  • refined_search : ce champ contient les requêtes mises à jour qui intègrent la dernière entrée de l'utilisateur final. Vous devez mettre à jour la console client pour la requête actuelle en conséquence (par exemple, en montrant que la requête visible par l'utilisateur est passée de "décorations" à "décorations pour une fête d'anniversaire" ou "articles pour une fête d'anniversaire"). Les requêtes refined_search peuvent être utilisées pour les appels à l'API Search principale (SearchService.Search) ou peuvent également être affichées à l'utilisateur final sous forme de suggestions.
  • conversational_text_response : affiche la nouvelle réponse textuelle générée par l'IA et pertinente pour le dernier tour de conversation.
  • followup_question : si la conversation doit se poursuivre pour affiner davantage la réponse, un nouveau followup_question est fourni.

Événements à envoyer à Vertex AI Search pour le commerce

Le taggage des événements est important pour attribuer précisément les requêtes de recherche aux interactions conversationnelles et pour utiliser les fonctionnalités d'analyse de Vertex AI Search pour le commerce.

Le processus de taggage d'événements comporte deux étapes :

  1. Récupérer conversation_id Lorsque vous effectuez un appel d'API conversationalSearch, ConversationalSearchResponse.conversation_id est renvoyé.
  2. Taggez les événements utilisateur. Dans les cas où la réponse conversationnelle conduit à une requête de recherche, par exemple en affichant une suggestion refined_search, ou si votre système exécute automatiquement une recherche en fonction de la requête affinée, vous devez taguer cet événement utilisateur de recherche ultérieur (UserEvent) avec le même conversation_id reçu dans le ConversationalSearchResponse.

En taggant correctement UserEvent.conversation_id, vos données analytiques peuvent attribuer avec précision les requêtes de recherche aux interactions conversationnelles précédentes. Vous obtenez ainsi des insights précieux sur le comportement des utilisateurs finaux et les chemins de conversion.

Intégrer l'agent au filtrage conversationnel des produits

Ce guide explique comment intégrer l'API conversationnelle et le filtrage conversationnel des produits pour proposer une expérience d'achat optimisée par l'IA. Lorsque conversationalFilteringSpec.mode est défini sur ENABLED, votre système peut passer directement des interactions conversationnelles ouvertes au filtrage guidé des produits, ce qui offre un parcours utilisateur très raffiné.

Comprendre l'interaction

Lorsque l'agent de commerce conversationnel et le filtrage conversationnel des produits sont activés, le système tire parti des avantages de chacun. L'agent de commerce conversationnel traite les requêtes générales, fournit des réponses générées par l'IA et affine les intentions initiales, tandis que le filtrage conversationnel des produits guide les utilisateurs dans la sélection d'attributs de produits spécifiques à l'aide d'un modèle d'interaction simplifié basé sur des chips ou des tuiles.

Le point d'interaction et de transition potentielle entre ces deux modes se produit lorsque la classification de l'API Conversational Commerce conduit à une recherche axée sur les produits, plus précisément SIMPLE_PRODUCT_SEARCH. À ce stade, l'API peut fournir une requête de recherche directe ou, si l'intention de l'utilisateur peut être affinée, elle déclenche un flux de filtrage guidé grâce au filtrage conversationnel de produits.

Un principe clé de cette intégration est que toutes les entrées en texte libre sont gérées par l'API Conversational Commerce, tandis que les clics sur les suggestions de réponses qui s'affichent sous forme de chips sont gérés par le filtrage conversationnel des produits.

Envoyer une requête utilisateur

Exemple d'entrée utilisateur : Aide-moi à organiser une fête

Pour activer à la fois l'agent de commerce conversationnel et le filtrage conversationnel des produits, assurez-vous que votre ConversationalSearchRequest inclut la configuration suivante :

Requête API Conversational Commerce : requête initiale

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

Voici les principales configurations :

  • Conversational_filtering_mode: ENABLED : si vous définissez ce champ sur ENABLED dans votre conversationalFilteringSpec, vous informez l'API que votre système peut gérer le filtrage conversationnel des produits. L'API peut ainsi fournir des réponses pertinentes spécifiques au filtrage.

Réponse initiale : affinement de l'intention

Le champ userQueryTypes reste essentiel pour comprendre l'intention de l'utilisateur. Pour une requête large initiale comme Aide-moi à organiser une fête,l'API la classera probablement comme INTENT_REFINEMENT si une recherche de produit plus spécifique n'est pas immédiatement claire.

Réponse de Google

Réponse de l'API Conversational Commerce : requête initiale

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

Action

  1. Affichez les conversationalTextResponse.
  2. Présentez les suggestions refinedSearch sous forme de chips cliquables pour Décorations, Snacks. Vous pouvez également appeler l'API Commerce Search en parallèle à l'aide des requêtes refined_search pour afficher les résultats de produits pertinents, par exemple pour Décorations, Snacks sous forme de carrousel, en plus de l'échange conversationnel.
  3. Affichez le followupQuestion : Quel type de fête prévoyez-vous d'organiser ?
  4. Autorisez la saisie utilisateur au format libre pour faire avancer la conversation.

Ajout de balises d'événement et analyse

Pour garantir l'exactitude des données analytiques et de l'attribution pour l'interaction conversationnelle initiale :

  • Récupérer conversation_id Capturez conversation_id à partir de ConversationalSearchResponse. Cet ID est essentiel pour associer toutes les actions suivantes à cette session de conversation spécifique.
  • Taggez les événements utilisateur. Si la réponse conversationnelle conduit à une requête de recherche, par exemple si votre système exécute automatiquement une recherche basée sur une requête refined_search ou si l'utilisateur clique sur une suggestion refined_search, vous devez taguer cet événement utilisateur de recherche ultérieur (UserEvent) avec le même conversation_id.

Requête complémentaire

Lorsque l'utilisateur répond à la question followupQuestion, la conversation s'affine.

Exemple d'entrée utilisateur : Une fête d'anniversaire

Affinement de l'intention | Extraits de code

Requête API Conversational Commerce : requête de suivi

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

Réponse de l'API Conversational Commerce : requête de suivi

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

Action

  1. Comme pour la réponse initiale, mettez à jour l'interface Web avec les nouvelles suggestions conversationalTextResponse, refinedSearch et followupQuestion.
  2. Poursuivez la conversation en demandant plus de détails.

Ajout de balises d'événement et analyse

Lorsque l'utilisateur poursuit la conversation :

  • Récupérer conversation_id Assurez-vous que le conversation_id du ConversationalSearchResponse précédent est transmis au ConversationalSearchRequest actuel.
  • Taggez les événements utilisateur. Si la réponse conversationnelle conduit à une nouvelle requête de recherche, par exemple parce qu'un utilisateur a cliqué sur une suggestion refined_search ou que votre système a effectué un appel de recherche parallèle, taguez cet événement utilisateur de recherche ultérieur (UserEvent) avec le même conversation_id. Cela permet de suivre le parcours conversationnel multitours.

Passer au filtrage conversationnel des produits

À mesure que la conversation devient plus spécifique, le système peut classer l'intention comme SIMPLE_PRODUCT_SEARCH et, le cas échéant, déclencher le filtrage conversationnel des produits.

Exemple d'entrée utilisateur : Thème princesse

Requête API Conversational Commerce : requête de suivi

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

Lorsqu'une requête est classée comme SIMPLE_PRODUCT_SEARCH, deux réponses d'API sont possibles, selon que le filtrage conversationnel des produits est déclenché ou non. La principale différence réside dans la présence et le contenu du champ conversationalFilteringResult.

Résultat 1 : le filtrage est déclenché

Cela se produit lorsque la requête est suffisamment générique pour être affinée davantage par des attributs de produit. La réponse inclut conversationalFilteringResult, que votre interface Web doit privilégier.

Réponse de l'API Conversational Commerce : transition vers le filtrage des produits 

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

Action

La requête a été classée comme SIMPLE_PRODUCT_SEARCH. Dans ce cas, le filtrage conversationnel de produits est déclenché. Toutefois, il est possible qu'il ne déclenche pas le filtrage conversationnel des produits.

  • Priorisez l'interface Web de filtrage des produits conversationnels : lorsque conversationalFilteringResult est renseigné, cela indique que vous avez activé le mode de filtrage des produits. Votre interface Web doit mettre l'accent sur followupQuestion, qui apparaît dans l'interface utilisateur sous la forme Quel type de décoration de princesse recherchez-vous ?, et sur suggestedAnswers, comme les boutons cliquables Ballons, Serpentins, Nappes.
  • Afficher les résultats des produits : appelez immédiatement l'API Retail Search à l'aide de refined_search.query (décorations d'anniversaire de princesse) pour afficher les premiers résultats de produits ainsi que les options de filtrage.
  • Pratique recommandée pour l'expérience utilisateur : il doit y avoir une seule barre de saisie de texte libre persistante pour l'ensemble de l'expérience. Cette barre reste active à tout moment, y compris pendant un parcours de filtrage conversationnel de produits. Lorsque conversationalFilteringResult est actif et que vous affichez des réponses suggérées sous forme de chips cliquables, les utilisateurs ont deux options claires :
    • Poursuivez le filtrage en cliquant sur une réponse suggérée.
    • Démarrez une nouvelle conversation en saisissant une nouvelle requête dans la barre de texte active. Cette nouvelle entrée déclenche toujours un nouvel appel à l'API Conversational Commerce, ce qui met fin au flux de filtrage actuel.

Résultat 2 : Aucun filtrage n'est déclenché

Si la requête est déjà suffisamment spécifique ou ne se prête pas à un filtrage plus poussé, la réponse n'inclut pas le champ conversationalFilteringResult. Dans ce cas, vous devez effectuer une recherche standard.

Action

  • Traitez l'interaction comme la fin du flux conversationnel et utilisez la requête refined_search pour appeler l'API Retail Search et afficher une page de résultats de produits standard.

Ajout de balises d'événement et analyse

Lorsque la conversation passe au filtrage des produits :

  • Récupérer conversation_id Continuez à utiliser le même conversation_id.
  • Taggez les événements utilisateur. Si la transition mène à une recherche immédiate, taguez cette UserEvent avec conversation_id. Il est important de noter que lorsque l'utilisateur interagit avec suggestedAnswers, par exemple lorsqu'il clique sur Balloons,cette action doit également déclencher un UserEvent tel qu'un événement filter ou un nouvel événement search, qui est tagué avec le même conversation_id. Cela permet d'attribuer les actions de filtrage dans le flux conversationnel.

Continuer dans le filtrage conversationnel de produits

Lorsque l'utilisateur sélectionne un suggestedAnswer, envoyez un nouveau ConversationalSearchRequest.

Exemple d'entrée utilisateur (clic sur une réponse suggérée) : Ballons

Recherche simple de produits | Extraits de code

Requête API Conversational Commerce : continuer le filtrage 

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

Réponse de l'API Conversational Commerce : continuer le filtrage 

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

Action

L'API répond avec une requête SIMPLE_PRODUCT_SEARCH, mais sans le champ conversationalFilteringResult, ce qui indique que le flux de filtrage guidé est terminé.

  • Utilisez la requête refinedSearch finale (ballons anniversaire princesse) pour appeler directement l'API Retail Search.
  • Affichez les résultats du produit final à l'utilisateur. À ce stade, la conversation peut se terminer ou l'utilisateur peut saisir une nouvelle requête pour commencer un nouveau tour.

Ajout de balises d'événement et analyse

Pour chaque étape du processus de filtrage des produits :

  • Récupérer conversation_id Utilisez toujours le même conversation_id pour toutes les requêtes de la session de filtrage.
  • Taggez les événements utilisateur. Chaque interaction utilisateur avec un suggestedAnswer, comme un clic, doit déclencher un UserEvent pertinent, comme un événement filter ou un nouvel événement search si une nouvelle requête est formée. Cette UserEvent doit être taguée avec conversation_id pour suivre précisément le parcours de filtrage et son impact sur les conversions.

Recommandations et choix de conception pour l'interface utilisateur

L'interaction entre l'agent de commerce conversationnel et le filtrage conversationnel de produits offre une grande flexibilité. Voici quelques points clés à prendre en compte pour créer une expérience fluide et intuitive :

  • Barre de saisie unique : l'expérience ne doit comporter qu'une seule barre de saisie de texte libre. Il n'existe pas de barre de saisie distincte et dédiée au filtrage conversationnel des produits. Cela simplifie l'interface utilisateur et assure une interaction cohérente.
  • Transitions fluides : concevez votre interface Web de manière à ce que les transitions entre les réponses conversationnelles, les requêtes suggérées et les options de filtrage soient naturelles et intuitives.
  • Instructions claires : utilisez des repères visuels, comme des styles de boutons distincts pour les réponses suggérées au lieu d'une saisie générale, et des instructions claires pour guider l'utilisateur sur la façon d'interagir à chaque étape.
  • Équilibre du contrôle : l'utilisateur doit toujours avoir l'impression de contrôler le déroulement de la conversation.
    • Filtrage vs saisie de texte libre : la barre de saisie de texte libre unique reste active à tout moment. L'utilisateur a ainsi le choix : il peut cliquer sur une réponse suggérée pour continuer à affiner sa recherche ou saisir une nouvelle requête dans la barre de texte pour lancer une nouvelle conversation. Cette conception garantit que même pendant un flux de filtrage, l'utilisateur peut passer à un autre sujet si ses besoins changent.
    • Option de réinitialisation : proposez une option Démarrer une nouvelle conversation ou Réinitialiser les filtres claire pour permettre aux utilisateurs de recommencer leur recherche ou leur processus de filtrage.

  • Persistance visuelle : même lors du passage au filtrage des produits, le fait de conserver l'historique des conversations dans la fenêtre de chat, par exemple en affichant les questions et réponses précédentes, peut améliorer le contexte et l'expérience utilisateur.

Autres points à prendre en compte et bonnes pratiques

Vous devez tenir compte d'autres considérations et bonnes pratiques lorsque vous implémentez l'interface de votre agent de commerce conversationnel :

  • Cohérence des ID de visiteur : permet de s'assurer qu'un visitor_id unique est envoyé de manière cohérente avec chaque requête pour un utilisateur final donné. C'est essentiel pour une personnalisation et un entraînement de modèle précis. Dans l'idéal, cet identifiant doit rester cohérent pour un utilisateur final, quelle que soit la session et qu'il soit connecté ou déconnecté.
  • Gestion des branches : bien que default_branch soit courant, assurez-vous d'utiliser le bon ID de branche si votre catalogue de produits est structuré avec plusieurs branches.
  • Interaction avec l'API Search : pour SIMPLE_PRODUCT_SEARCH et tous les cas où refined_search est fourni, n'oubliez pas d'effectuer un appel distinct à l'API Search principale (SearchService.Search) en utilisant le query du champ refined_search ou la requête d'origine pour obtenir les fiches produit réelles. L'API Conversationnel se concentre principalement sur l'expérience conversationnelle et la compréhension de l'intention de l'utilisateur plutôt que sur le renvoi direct de résultats de produits.
  • Conception de l'interface utilisateur : concevez votre interface Web pour présenter clairement les options conversational_text_response, followup_question et refined_search de manière intuitive afin de guider votre utilisateur.

Étapes suivantes

Pour obtenir d'autres ressources d'assistance, consultez les questions fréquentes sur les fonctionnalités conversationnelles.