Guida per gli sviluppatori di agenti di commercio conversazionale

Questa guida descrive in dettaglio come eseguire l'integrazione con l'API Conversational per fornire ai tuoi clienti esperienze di chat dinamiche basate sull'AI. Comprendendo i diversi tipi di query e sfruttando le risposte dell'API, puoi fornire ricerche di prodotti pertinenti, rispondere alle domande dei clienti e guidare gli utenti finali nel loro percorso di acquisto.

L'conversationalFilteringMode nell'API Conversazionale chiarisce le differenze tra l'agente di Commercio conversazionale e il filtro conversazionale dei prodotti.

Configurazione

L'API Conversational supporta la funzionalità dell'agente di Commercio conversazionale:

• gRPC: conversationalSearchService
• REST: conversationalSearch

L'API Conversational consente un'esperienza di chat in cui gli utenti inviano query e il sistema restituisce una risposta di testo, i tipi di query classificati e potenziali opzioni di ricerca perfezionate.

Questa API funziona come un servizio di streaming, consentendo il rilevamento precoce dell'intento della query. Le interazioni successive nella conversazione richiedono l'allegato di un conversation_id.

Per restituire i risultati di ricerca, l'API Retail precedente deve essere chiamata in parallelo all'API Conversational.

Invia una query dall'utente finale

Questa sezione descrive come avviare un'esperienza con l'agente di Commercio conversazionale. Ad esempio, l'utente potrebbe inserire Aiutami a organizzare una festa nel campo di ricerca.

Invia una richiesta a Vertex AI Search for Commerce

Esistono due endpoint API diversi:

1. Per recuperare l'esperienza conversazionale, devi utilizzare l'API Conversational.
2. Per recuperare i risultati di ricerca, è necessario utilizzare l'API Search principale.

Endpoint 1: richiesta API conversazionale

• Devi creare una richiesta di agente di Conversational Commerce impostando l'input dell'utente come query.
• La richiesta deve essere inviata come richiesta HTTP POST all'endpoint projects/*/locations/*/catalogs/*/placements/*:conversationalSearch.

Metodo HTTP ed endpoint

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

Richiesta API conversazionale:

Query iniziale

{
  "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: il nome risorsa del posizionamento (ad esempio projects/your-project-id/locations/global/catalogs/default_catalog/placements/default_branch). Si tratta di un parametro di percorso obbligatorio.
• query: la query di ricerca non elaborata dell'utente. Questo campo è obbligatorio.
• branch: il nome della risorsa ramo, ad esempio projects/P/locations/L/catalogs/C/branches/B. Se non è impostato, viene utilizzato default_branch. Questo campo è obbligatorio.
• visitorId: un identificatore univoco per monitorare i visitatori. Questo campo è obbligatorio.
• conversationId: un ID univoco per monitorare le sessioni di conversazione. Per la richiesta iniziale in una nuova conversazione, questo campo deve essere vuoto. Per le richieste successive all'interno della stessa conversazione, deve essere impostato sul conversation_id ricevuto nel ConversationalSearchResponse precedente.
• searchParams: (facoltativo) parametri di ricerca principali standard, come filter, canonicalFilter, sortBy e boostSpec. È fondamentale che questi parametri riflettano la configurazione utilizzata nelle chiamate API Search principali per garantire la coerenza tra le risposte del LLM e i risultati di ricerca dei prodotti visualizzati.
• userInfo: (facoltativo) informazioni sull'utente per una personalizzazione avanzata. Può includere userId, user_agent, direct_user_request (booleano).
• conversationalFilteringSpec: (facoltativo) specifica la modalità di filtro conversazionale. Se non viene impostato, il valore predefinito è DISABLED.

  mode: integra l'API Conversational utilizzando una di queste tre modalità per controllare il filtro dei prodotti conversazionale:

• DISABLED: in questa modalità, il cliente implementa solo la ricerca dell'agente di Commercio conversazionale. Questa è la modalità preferita per questa guida all'implementazione della ricerca dell'agente di Commercio conversazionale.

Richiesta API di esempio

        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
        }
      

Esempio di risposta dell'API

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

• ENABLED: in questa modalità, il client implementa tutte le funzionalità conversazionali, tra cui la ricerca dell'agente di Commercio conversazionale e il filtro conversazionale dei prodotti.

Consulta la guida aggiuntiva su come integrare entrambi i prodotti conversazionali.

Richiesta API di esempio

        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
        }
      

Esempio di risposta dell'API

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

• CONVERSATIONAL_FILTER_ONLY: se selezionato, il cliente implementa il filtro dei prodotti conversazionale solo. Con questa modalità selezionata, l'utente sperimenta solo il filtro conversazionale dei prodotti senza generare una risposta LLM, una classificazione delle query o query di ricerca suggerite.

Per ulteriori informazioni, consulta la Guida per gli sviluppatori del filtro dei prodotti conversazionale.

Endpoint 2: richiesta API Core Search

Esistono due approcci principali per visualizzare i risultati di ricerca nell'interfaccia web.

Opzione 1: mostra sempre i risultati di ricerca

Se la progettazione dell'esperienza utente prevede che i risultati di ricerca vengano sempre visualizzati indipendentemente dall'output conversazionale, ad esempio in un'area dedicata ai risultati di ricerca accanto alla chat, invia la query originale dell'utente all'API Product Search di base con la chiamata all'API Conversational. In questo modo, le schede di prodotto sono immediatamente disponibili.

Opzione 2: mostra i risultati di ricerca in base all'output conversazionale

Se il design dell'esperienza utente è più dinamico e vuoi visualizzare i risultati di ricerca solo in base alla risposta dell'API Conversational, ad esempio solo per le query SIMPLE_PRODUCT_SEARCH o ogni volta che vengono forniti suggerimenti refined_search, attendi la risposta dell'API Conversational prima di inviare query all'API Product Search principale. Se è presente una risposta, utilizza la query refined_search fornita per recuperare i risultati dei prodotti.

Indipendentemente dall'opzione dell'interfaccia utente scelta, quando devi recuperare i risultati effettivi dei prodotti, puoi effettuare una chiamata all'API Retail. Per saperne di più, consulta la sezione Informazioni sui tipi di query e sulle azioni del rivenditore.

Metodo HTTP ed endpoint

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

Richiesta API di ricerca del prodotto principale:

Query iniziale

    {
      "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 (obbligatorio): il nome risorsa della configurazione di pubblicazione di Retail Search o del posizionamento precedente. Esempio: projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/servingConfigs/default_search.
• query: obbligatorio. La query di ricerca. Può trattarsi dell'input grezzo dell'utente, ad esempio Aiutami a organizzare una festa, o di un refinedSearch.query più ottimizzato (ad esempio articoli per l'organizzazione di feste, decorazioni) ottenuto dalla risposta dell'API Conversational Commerce.
• visitorId: obbligatorio. Un identificatore univoco per il monitoraggio dei visitatori. Questo valore deve essere coerente con visitorId inviato all'API Conversational Commerce per lo stesso utente finale.
• branch (obbligatorio): il nome della risorsa del ramo, ad esempio projects/YOUR_PROJECT_ID/locations/global/catalogs/default_catalog/branches/default_branch.
• pageSize (facoltativo): il numero massimo di prodotti da restituire.
• filter (facoltativo): utilizzato per filtrare i risultati di ricerca. È qui che applicheresti tutti i filtri che rispecchiano ciò che invii in `searchParams` all'API Conversational Commerce per coerenza.
• orderBy (facoltativo): specifica l'ordine in cui vengono restituiti i prodotti (ad esempio per pertinenza o per prezzo).
• userInfo (Facoltativo): informazioni utente per la personalizzazione, devono essere coerenti con la chiamata API Conversational Commerce.
• searchMode (facoltativo): definisce il comportamento di ricerca. PRODUCT_SEARCH è comune per le query generali sui prodotti.

Comprendere la risposta

Questo esempio di codice mostra una risposta dell'API Conversational Commerce.

La risposta dell'API (ConversationalSearchResponse) include query_types, conversational_text_response (se applicabile), opzioni refined_search e potenzialmente un followup_question o un conversational_filtering_result. Il conversation_id è essenziale per continuare la sessione.

Risposta di Vertex AI Search for Commerce

Questo esempio di codice mostra una risposta dell'API Conversational:

Risposta iniziale

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

Cosa devono fare i rivenditori con la risposta (generale)

Visualizza questi campi dalla risposta:

• user_query_types: questo campo fornisce la classificazione o le classificazioni dell'intent dell'utente. Per azioni dettagliate basate su questi tipi, consulta Comprendere i tipi di query e le azioni del rivenditore.
• conversation_id: puoi memorizzare questo ID univoco nell'archivio della sessione del browser o in un archivio lato client simile per mantenere la sessione conversazionale con il server. Questo è fondamentale per distinguere più conversazioni in corso per un singolo acquirente. Il modello conserva il contesto per un determinato conversation_id. L'invio di un nuovo conversation_id avvia una nuova sessione. Ti consigliamo di definire la durata della sessione, ad esempio 30 minuti di inattività.
• refined_search: questo è un elenco di query di ricerca perfezionate proposte utilizzate per recuperare i risultati di ricerca pertinenti. Per SIMPLE_PRODUCT_SEARCH, si tratta sempre di una singola query. Per le altre query che cercano risposte LLM, è una o più. Le query refined_search possono essere utilizzate per le chiamate all'API Search principale (SearchService.Search) o possono anche essere visualizzate all'utente come suggerimenti.
• conversational_text_response: mostra questo testo all'utente come risposta principale generata dall'AI alla sua query.
• followup_question: facoltativo. Viene visualizzato followup_question.
• state: questo campo indica lo stato della generazione della risposta ("STREAMING" o "SUCCEEDED"). Puoi utilizzarlo per il feedback sull'esperienza utente, ad esempio per mostrare un indicatore di caricamento fino a "SUCCEEDED". Scopri di più nella sezione successiva.

Informazioni sull'API di streaming

L'API Conversational Commerce funziona come un'API di streaming. Ciò significa che l'utente riceve parti della risposta in più blocchi anziché un singolo payload completo.

Il primo blocco della risposta include le query query_types e refined_search e il relativo state è indicato come STREAMING. Questa rilevazione precoce dell'intent e la disponibilità immediata dei perfezionamenti della ricerca consentono al modello di prendere decisioni rapide su come gestire la query dell'utente e la sua esperienza in termini di latenza delle risposte LLM:

• Per i tipi di query che non prevedono una risposta di testo conversazionale, ad esempio SIMPLE_PRODUCT_SEARCH, RETAIL_IRRELEVANT, BLOCKLISTED, QUERY_TYPE_UNSPECIFIED, ORDER_SUPPORT, DEALS_AND_COUPONS, STORE_RELEVANT:
• Poiché query_types si trova nel primo blocco, il sistema sa immediatamente che non arriverà alcuna risposta del modello LLM. Puoi procedere con la gestione predefinita per questi tipi, ad esempio visualizzare un messaggio statico, reindirizzare all'assistenza, senza attendere ulteriori output conversazionali.
• Nello specifico per SIMPLE_PRODUCT_SEARCH, il tuo sistema può effettuare immediatamente una chiamata diretta all'API Search principale utilizzando la query refined_search ricevuta nel primo blocco. Ciò contribuisce a garantire che i risultati di ricerca vengano visualizzati con un ritardo minimo, rispettando i tipici SLA dell'esperienza di ricerca.
• Per i tipi di query che prevedono una risposta di testo conversazionale, ad esempio INTENT_REFINEMENT, PRODUCT_DETAILS, PRODUCT_COMPARISON, BEST_PRODUCT:
• Ricevi le query query_types e refined_search nel blocco iniziale. Puoi avviare immediatamente una chiamata parallela all'API Search utilizzando queste query refined_search per iniziare a caricare i risultati dei prodotti.
• I chunk successivi vengono trasmessi in streaming e contengono sezioni diverse della risposta di testo conversazionale. Durante questo periodo, state rimane "STREAMING".
• Infine, l'ultimo blocco include la risposta completa in formato di testo conversazionale e il relativo state cambia in "COMPLETED".
• Questo approccio di streaming consente un'esperienza utente finale fluida in cui i risultati di ricerca possono iniziare a caricarsi mentre viene generato il riepilogo dell'AI. Puoi scegliere di visualizzare un indicatore di caricamento per la risposta conversazionale o di presentarla dopo che è stata completamente trasmessa in streaming.

Informazioni sui tipi di query e sulle azioni dei rivenditori

Il campo query_types nella risposta è un elenco che indica la classificazione o le classificazioni dell'intent dell'utente. Il sistema dovrebbe gestirli nel seguente modo. Tieni presente che conversational_text_response si riferisce alla risposta in linguaggio naturale generata dall'AI dall'API.

L'agente di Commercio conversazionale utilizza le categorie di query di ricerca per determinare se viene generata una risposta basata su LLM e come vengono gestite le query degli utenti finali dalle API Conversational e Search per questi scenari:

Categorie	Classificazioni delle query
#1. Query non pertinenti che non richiedono una risposta LLM	QUERY_TYPE_UNSPECIFIED: Tipo di query non specificato. RETAIL_IRRELEVANT: query non pertinenti al dominio della vendita al dettaglio, ad esempio una query ostile (come come costruire una bomba), una query colloquiale (come come stai) o una query di jailbreak (come scrivi una poesia). BLOCKLISTED: query bloccate esplicitamente dai clienti di commercio (ad esempio Quali sono gli effetti collaterali dell'Advil?).
#2. Richieste di assistenza e informazioni	ORDER_SUPPORT: query ausiliaria o di assistenza (ad esempio Traccia il mio ordine, Stato ordine 12345). DEALS_AND_COUPONS: query pertinenti a offerte, promozioni, offerte di prodotti e sconti (ad esempio Ci sono offerte per il giorno del Ringraziamento?) STORE_RELEVANT: query pertinenti alle sedi dei negozi, inclusi orari di apertura e disponibilità di scorte di prodotti (ad esempio Abbiamo latte in magazzino?). RETAIL_SUPPORT: query pertinenti agli acquisti, inclusi i metodi di pagamento (Quale metodo di pagamento accettate?).
#3. Ricerche di parole chiave che non richiedono LLM Richiesta API conversazionale: Query iniziale { "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" } Risposta dell'API conversazionale: Risposta iniziale { "userQueryTypes": ["SIMPLE_PRODUCT_SEARCH"], "conversationId": "479fd093-c701-4899-bcc3-9e711233bdf9", "refinedSearch": [ { "query": "monster energy drinks" } ] } Richiesta dell'API Search: Query di follow-up { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "monster energy drinks", "visitorId": "test" }	SIMPLE_PRODUCT_SEARCH: ricerca di base di prodotti, ad esempio vestito rosso o mostrami alcune bevande Monster.
#4. Query di ricerca di risposte LLM Richiesta API conversazionale: Query iniziale { "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" } Risposta dell'API conversazionale: Risposta iniziale { "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" } ] } Richiesta dell'API Search: Query di follow-up { "placement": "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search", "query": "1% milk", "visitorId": "test" }	PRODUCT_DETAILS: l'utente sta cercando dettagli e specifiche del prodotto, ad esempio mostrami le specifiche di [nome prodotto], qual è il contenuto proteico del latte al 2%? PRODUCT_COMPARISON: confronto tra prodotti, ad esempio confronta [nome prodotto] e [nome prodotto], confronta il latte all'1% con il latte al 2%. BEST_PRODUCT: query con il pattern di corrispondenza più elevato, ad esempio Qual è il biscotto più sano? Qual è la migliore marca di latte?
#5. Perfezionamento dell'intent Richiesta API conversazionale: Query iniziale { "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" } Risposta dell'API conversazionale: Risposta iniziale { "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: il tipo non è chiaro e potrebbe essere necessario un ulteriore scambio o perfezionamento per chiarirlo, ad esempio Aiutami a organizzare una festa. Si tratta spesso dell'intent più popolare nelle conversazioni.

Categoria 1. Query non pertinenti che non richiedono una risposta LLM

• QUERY_TYPE_UNSPECIFIED:
• Nessun conversational_text_response fornito.
• Azione: gestisci come caso predefinito o di errore. Potresti chiedere all'utente un chiarimento o indirizzarlo a una pagina in cui può ricevere assistenza generale.
• RETAIL_IRRELEVANT:
• Nessun conversational_text_response fornito.
• Azione: gestisci la situazione mostrando un messaggio appropriato, ad esempio Non posso rispondere a questa domanda o Sono un assistente allo shopping, come posso aiutarti?, come definito dalla progettazione della tua applicazione.
• BLOCKLISTED:
• Non è stato fornito alcun conversational_text_response.
• Azione: gestisci in base alle norme relative alla lista bloccata, in genere mostrando un messaggio generico Impossibile soddisfare questa richiesta.

Categoria 2. Richieste di assistenza e informazioni

Per questi tipi, l'API non fornisce un conversational_text_response diretto per impostazione predefinita, ma hai opzioni per indirizzare ai link o alle risorse giusti.

• ORDER_SUPPORT:
• Azione predefinita: non viene fornito alcun conversational_text_response. L'interfaccia web deve mostrare un messaggio standard, link pertinenti o reindirizzare la query alla tua API di assistenza dedicata o al tuo canale di assistenza clienti.
• DEALS_AND_COUPONS:
• Azione predefinita: non viene fornito alcun conversational_text_response. L'interfaccia web deve mostrare un messaggio standard, link pertinenti o reindirizzare la query al sistema di offerte o promozioni.
• STORE_RELEVANT:
• Azione predefinita: non viene fornito alcun conversational_text_response. La tua interfaccia web deve mostrare un messaggio standard, link pertinenti o reindirizzare la query al tuo sistema di informazioni o localizzatore di negozi.
• RETAIL_SUPPORT:
• Azione predefinita: non viene fornito alcun conversational_text_response. L'interfaccia web deve mostrare un messaggio standard, link pertinenti o reindirizzare la query al tuo sistema di domande frequenti e informazioni.

Categoria 3. Ricerche di parole chiave che non richiedono risposte LLM

• SIMPLE_PRODUCT_SEARCH:
• Non viene generata alcuna risposta di testo conversazionale.
• Azione: la risposta API restituisce sempre una singola query refined_search. Questa query perfezionata funge da termine di ricerca suggerito. Chiama direttamente l'API Search principale (SearchService.Search) e recupera i risultati dei prodotti pertinenti utilizzando la query originale o la query refined_search. refined_search.query potrebbe non derivare direttamente dall'input utente finale corrente, ma può essere derivato anche dal contesto della cronologia della chat. Ad esempio, se un utente finale ha precedentemente perfezionato abito da festa in abiti rossi, la query perfezionata potrebbe diventare abito da festa rosso.
• Per le interfacce conversazionali (come i chatbot): è vivamente consigliato utilizzare l'refined_search.query fornito dall'API. In un flusso conversazionale, le query in linguaggio naturale come "puoi aiutarmi a trovare le banane?" vengono ottimizzate automaticamente dall'API in un termine di ricerca di prodotto preciso ("banane"), il che porta a risultati di prodotto più pertinenti.
• Per le esperienze di ricerca principali (ad esempio la pagina dei risultati di ricerca): puoi utilizzare in modo flessibile refined_search.query dall'API o la query originale fornita dall'utente finale, perché è più probabile che la query originale sia già un termine di ricerca di prodotto preciso. Scegli l'opzione più adatta alla tua interfaccia web e alla tua strategia di visualizzazione dei risultati di ricerca.
• Opzioni di esperienza utente: la conversazione non deve terminare per le query SIMPLE_PRODUCT_SEARCH. L'utente può continuare la conversazione passando il conversation_id nelle richieste successive.
• Opzione A: termina l'interfaccia web conversazionale: molti rivenditori scelgono di reindirizzare l'utente a una pagina dei risultati di ricerca standard una volta rilevato un SIMPLE_PRODUCT_SEARCH, chiudendo di fatto la finestra della chat. In questo scenario, se l'utente finale inserisce una nuova query nella casella di ricerca standard senza il precedente conversation_id, viene trattata come una nuova conversazione separata e viene emesso un nuovo conversation_id.
• Opzione B: continua con l'interfaccia web conversazionale: i rivenditori possono scegliere di mantenere aperta la finestra della chat. In questo modo, l'utente può tornare alla modalità conversazionale. La decisione di implementare l'opzione A o B dipende interamente dall'esperienza utente preferita dal rivenditore.

Per attribuire con precisione le query di ricerca alle interazioni conversazionali e utilizzare tutte le funzionalità di analisi in Vertex AI Search for Commerce, è fondamentale taggare correttamente gli eventi:

1. Recupera conversation_id. Quando effettui una chiamata API conversationalSearch, viene restituito ConversationalSearchResponse.conversation_id.
2. Tagga gli eventi utente. Nei casi in cui la risposta conversazionale porta a una query di ricerca, ad esempio se il sistema esegue automaticamente una ricerca in base alla query perfezionata per SIMPLE_PRODUCT_SEARCH, devi taggare l'evento utente di ricerca successivo (UserEvent) con lo stesso conversation_id ricevuto in ConversationalSearchResponse.

Se tagghi correttamente UserEvent.conversation_id, Analytics può attribuire con precisione le query di ricerca alle interazioni conversazionali precedenti, fornendo informazioni preziose sul comportamento e sui percorsi di conversione degli utenti.

Categoria 4. Query di ricerca di risposte LLM

Per questi tipi di query, l'API genera una conversational_text_response (risposta LLM) e potrebbe anche fornire una o più query refined_search. La conversazione non termina e l'utente finale può continuare.

• PRODUCT_DETAILS:
• Azione: conversational_text_response fornisce i dettagli del prodotto richiesti. Il tuo sistema deve mostrare chiaramente queste informazioni all'utente.
• La risposta include anche refined_search (una o più query di ricerca suggerite, ordinate e classificate) che devono essere utilizzate per recuperare i risultati di ricerca utilizzando l'API Search principale.
• PRODUCT_COMPARISON:
• Azione: il conversational_text_response fornisce un confronto tra i prodotti specificati. Il tuo sistema deve mostrare chiaramente queste informazioni all'utente.
• La risposta include refined_search (una o più query di ricerca suggerite, ordinate e classificate) che devono essere utilizzate per recuperare i risultati di ricerca utilizzando l'API Search principale.
• BEST_PRODUCT:
• Azione: conversational_text_response fornisce consigli o informazioni sui prodotti che corrispondono meglio alla query. Il sistema dovrebbe visualizzare queste informazioni.
• La risposta include refined_search (una o più query di ricerca suggerite, ordinate e classificate) che devono essere utilizzate per recuperare i risultati di ricerca utilizzando l'API Search principale.

Categoria 5. Perfezionamento dell'intent

• INTENT_REFINEMENT:
• Azione: la risposta include conversational_text_response, un followup_question e refined_search (una o più query di ricerca suggerite). L'ordine di visualizzazione consigliato è il seguente:
1. conversational_text_response
2. Suggerimenti refined_search: sono ordinati e classificati, quindi è importante visualizzarli nello stesso ordine della risposta.
3. Followup_question
• La risposta include refined_search (una o più query di ricerca suggerite, ordinate e classificate) che devono essere utilizzate per recuperare i risultati di ricerca utilizzando l'API Search principale.
• Per le interazioni successive, invia la risposta dell'utente insieme a conversation_id.

Mostra query suggerite per i prodotti

Ecco come configurare la Ricerca Google per mostrare domande e suggerimenti sui prodotti nell'agente di commercio conversazionale.

Quando l'API Conversazionale restituisce query refinedSearch, queste query rappresentano ottime opportunità per indirizzare l'utente finale verso prodotti pertinenti. Ciò è particolarmente utile per la categoria 4 (query di ricerca di risposte LLM) e la categoria 5 (INTENT_REFINEMENT).

Consiglio

• Visualizzazione: mostra all'utente le prime N (1-3, in attesa di test sul numero ideale per la tua interfaccia web) refinedSearch query.
• Meccanismo: queste query suggerite devono essere eseguite in background o in seguito all'interazione dell'utente tramite l'API Search principale (SearchService.Search).
• Presentazione: mostra i risultati come caroselli interattivi o schede cliccabili, consentendo all'utente di sfogliare categorie di prodotti correlate o articoli specifici. In questo modo, si crea un valore immediato e si colma il divario tra l'interazione conversazionale e la scoperta dei prodotti.

Richiesta API Search:

Query di follow-up

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

Eventi da inviare a Vertex AI Search for Commerce

È importante attribuire con precisione le query di ricerca alle interazioni conversazionali e utilizzare tutte le funzionalità di analisi in Vertex AI Search for Commerce utilizzando il tagging degli eventi corretto:

1. Recupera conversation_id. Quando effettui una chiamata API conversationalSearch, viene restituito ConversationalSearchResponse.conversation_id.
2. Tagga gli eventi utente. Nei casi in cui la risposta conversazionale porta a una query di ricerca, ad esempio visualizzando un suggerimento refined_search su cui l'utente finale fa clic, o se il tuo sistema esegue automaticamente una ricerca in base alla query perfezionata, devi taggare l'evento utente di ricerca successivo (UserEvent) con lo stesso conversation_id ricevuto in ConversationalSearchResponse.

Se tagghi correttamente UserEvent.conversation_id, Analytics può attribuire con precisione le query di ricerca alle interazioni conversazionali precedenti, fornendo informazioni preziose sul comportamento degli utenti e sui percorsi di conversione.

Continua la conversazione

Questa sezione descrive in che modo le sessioni dell'agente di Conversational Commerce vengono gestite dall'API Conversational e continuano in questo passaggio finale.

L'API Conversazionale utilizza un conversation_id per gestire le conversazioni in corso. Per garantire la coerenza tra le risposte del modello linguistico di grandi dimensioni e i risultati di ricerca, le richieste Conversational API successive devono includere SearchParams che rispecchiano la configurazione delle chiamate API di ricerca principali.

Visualizza tabella

Gestione delle sessioni	Descrizione	Integrazione dell'API Conversational
Inizia una nuova conversazione	Per avviare una nuova conversazione, il client omette conversation_id dalla richiesta API.	Richiesta API di esempio placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Esempio di risposta dell'API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Continua la conversazione	L'API Conversational restituisce un conversation_id come parte della risposta dell'API. Questo ID può essere inviato nelle richieste successive per continuare la stessa conversazione. In questo modo, l'agente di Conversational Commerce risponde alle query dell'utente in base alla cronologia della conversazione nella sessione.	Richiesta API di esempio placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" Esempio di risposta dell'API user_query_types: "INTENT_REFINEMENT" conversational_text_response: "To plan a party, you\'ll need decorations, snacks, party supplies, drinks, and a cake." followup_question { followup_question: "What kind of party are you planning?" } conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" refined_search { query: "Decorations" }
Garantire la coerenza dei risultati di ricerca	Per garantire che le risposte del LLM siano coerenti con i risultati di ricerca mostrati, il client deve utilizzare SearchParams nella richiesta dell'API Conversational. Questi parametri di ricerca devono avere la stessa configurazione dell'API Search principale.	Richiesta API di esempio placement: "projects/118220807021/locations/global/catalogs/default_catalog/placements/default_search" branch: "projects/118220807021/locations/global/catalogs/default_catalog/branches/default_branch" conversation_id: "1577511e-36ed-4054-8e07-48d1ca016bcb" query: "Help me plan a party" conversational_filtering_spec { conversational_filtering_mode: ENABLED } visitor_id: "test" search_params { filter: "filter" canonical_filter: "canonical_filter" sort_by: "sort_by" boost_spec { condition_boost_specs { condition: "condition" } } }

Gestione delle sessioni

• Avvia una nuova conversazione:
  • Descrizione: per iniziare una nuova conversazione, il client omette conversationId dalla richiesta API.
  • Quando avviare una nuova conversazione: un cliente vorrebbe avviare una nuova conversazione, ottenendo così un nuovo conversationId dalla risposta dell'API, in diversi scenari comuni di esperienza utente:
    • Nuova scheda o sessione: quando un cliente apre il tuo sito in una nuova scheda del browser o avvia una sessione completamente nuova.
    • Nuova query originale: in alcuni design UX, se un cliente inserisce una nuova query non correlata, puoi scegliere di riavviare il flusso conversazionale per garantire il contesto più pertinente.
    • Pulsante Riavvia conversazione: se l'interfaccia web fornisce un pulsante esplicito Avvia nuova chat o Reimposta conversazione, facendo clic su questo pulsante si avvia una nuova sessione di conversazione.
  • Integrazione dell'API conversazionale: la risposta dell'API include un nuovo conversationId utilizzato per le richieste successive.
• Continua la conversazione:
  • Descrizione: Conversational API restituisce un conversation_id come parte della risposta dell'API. Questo ID deve essere inviato nelle richieste successive per continuare la stessa conversazione. In questo modo, l'agente di Conversational Commerce risponde alle query dell'utente in base alla cronologia della conversazione all'interno della sessione, coprendo l'query, l'conversational_text_response e l'followup_question dell'utente finale.
  • Integrazione dell'API conversazionale: il client passa conversation_id dalla risposta precedente in ConversationalSearchRequest.
• Garantisci la coerenza dei risultati di ricerca:
  • Descrizione: per garantire che le risposte del modello LLM siano coerenti con i risultati di ricerca mostrati all'utente, il client deve utilizzare searchParams nella richiesta Conversational API. Questi parametri di ricerca devono avere la stessa configurazione (ad esempio filtri, ordine di ordinamento) delle chiamate Search API effettuate per recuperare i risultati dei prodotti.
  • Integrazione dell'API conversazionale: l'oggetto searchParams all'interno di ConversationalSearchRequest deve essere compilato in modo identico a SearchRequest utilizzato per la ricerca di prodotti di base.

Invia una richiesta a Vertex AI Search for Commerce

Puoi recuperare conversation_id dall'archiviazione della sessione. La richiesta deve includere il nuovo query del cliente, che potrebbe essere una risposta alla domanda della risposta precedente. La richiesta deve includere anche l'refined_search.query più recente della risposta precedente se l'utente finale agisce in base a una query perfezionata. In caso contrario, deve includere una query completamente nuova e non correlata e il conversationId. Ricorda di includere sempre searchParams coerenti.

Nota :il mantenimento o il ripristino del conversationId per una nuova query dell'utente finale dipende dalle tue scelte specifiche in termini di UX e dall'esperienza utente selezionata. conversationId funge da memoria di sistema per una determinata sessione conversazionale.

• Scenario 1: singola barra di ricerca e conversazione persistente: se l'interfaccia di ricerca ha una sola barra di ricerca principale o una finestra di conversazione persistente, non reimposterai conversationId, anche se l'utente finale digita una nuova query apparentemente non correlata. Il sistema utilizza la cronologia delle conversazioni esistente (associata a conversationId) per fornire risposte contestualmente pertinenti.
• Scenario 2: finestra di conversazione e finestra di query separate: se l'interfaccia di ricerca include una finestra di chat conversazionale distinta e una barra di query di ricerca standard separata (ad esempio una casella di ricerca a livello di sito), l'inserimento di una nuova query nella barra di ricerca standard potrebbe segnalare implicitamente l'intenzione di avviare una nuova ricerca non correlata, il che potrebbe comportare il ripristino di conversationId per questa specifica azione di ricerca. Tuttavia, all'interno della finestra di conversazione dedicata, il conversationId deve essere sempre mantenuto per garantire la continuità.

In definitiva, la decisione su quando riutilizzare o reimpostare il conversationId è una scelta di progettazione per ottimizzare l'esperienza conversazionale per i tuoi clienti.

Metodo HTTP ed endpoint (uguale alla query iniziale)

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

Richiesta API conversazionale:

Query di follow-up

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

Risposta dell'API conversazionale:

Risposta di follow-up

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

Esempi di un utente finale che continua a ricevere domande:

• Domanda dell'utente: Aiutami a organizzare una festa.
• Risposta del sistema: Che tipo di festa stai organizzando?
• Risposta dell'utente: Una festa di compleanno.

Cosa devono fare i rivenditori con la risposta

Il modo di eseguire il rendering dei campi è simile alla risposta iniziale, ma nota le modifiche che riflettono la conversazione continua:

• refined_search: questo campo contiene le query aggiornate che incorporano l'ultimo input dell'utente finale. Devi aggiornare la console client per la query corrente di conseguenza (ad esempio, mostrando la query rivolta agli utenti che è cambiata da "decorazioni" a "decorazioni per feste di compleanno" o "articoli per feste di compleanno"). Le query refined_search possono essere utilizzate per chiamate all'API Search principale (SearchService.Search) o possono anche essere visualizzate all'utente finale come suggerimenti.
• conversational_text_response: mostra la nuova risposta di testo creata con l'AI pertinente all'ultimo turno.
• followup_question: se la conversazione deve continuare per ulteriori perfezionamenti, viene fornito un nuovo followup_question.

Eventi da inviare a Vertex AI Search for Commerce

Il tagging degli eventi è importante per attribuire con precisione le query di ricerca alle interazioni conversazionali e per utilizzare le funzionalità di analisi in Vertex AI Search for commerce.

Il processo di tagging degli eventi prevede due passaggi:

1. Recupera conversation_id. Quando effettui una chiamata API conversationalSearch, viene restituito ConversationalSearchResponse.conversation_id.
2. Tagga gli eventi utente. Nei casi in cui la risposta conversazionale porta a una query di ricerca, ad esempio visualizzando un suggerimento refined_search, o se il sistema esegue automaticamente una ricerca in base alla query perfezionata, devi taggare l'evento utente di ricerca successivo (UserEvent) con lo stesso conversation_id ricevuto in ConversationalSearchResponse.

Se tagghi correttamente UserEvent.conversation_id, Analytics può attribuire con precisione le query di ricerca alle interazioni conversazionali precedenti, fornendo informazioni preziose sul comportamento degli utenti finali e sui percorsi di conversione.

Integra l'agente con il filtro conversazionale dei prodotti

Questa guida descrive come eseguire l'integrazione con l'API conversazionale e il filtro dei prodotti conversazionale per offrire un'esperienza di acquisto basata sull'AI. Quando conversationalFilteringSpec.mode è impostato su ENABLED, il sistema può passare direttamente dalle interazioni conversazionali aperte al filtro guidato dei prodotti, offrendo un percorso dell'utente altamente raffinato.

Comprendere l'interazione

Quando sono attivi sia l'agente di Conversational Commerce sia il filtro conversazionale dei prodotti, il sistema sfrutta i punti di forza di ciascuno. L'agente di Commercio conversazionale gestisce le richieste generiche, fornisce risposte generate dall'AI e perfeziona gli intent iniziali, mentre il filtro conversazionale dei prodotti guida gli utenti nella selezione di attributi specifici dei prodotti utilizzando un modello di interazione semplificato basato su chip o riquadri.

Il punto di interazione e potenziale transizione tra queste due modalità si verifica quando la classificazione dell'API Conversational Commerce porta a una ricerca orientata al prodotto, in particolare SIMPLE_PRODUCT_SEARCH. A questo punto, l'API può fornire una query di ricerca diretta oppure, se l'intento dell'utente può essere ulteriormente perfezionato, attiva un flusso di filtraggio guidato tramite il filtro conversazionale dei prodotti.

Un principio fondamentale di questa integrazione è che tutti gli input di testo libero vengono gestiti dall'API Conversational Commerce, mentre i clic sulle risposte suggerite che vengono visualizzate come chip vengono gestiti dal filtro conversazionale dei prodotti.

Inviare la query utente

Esempio di input dell'utente: Aiutami a organizzare una festa

Per abilitare sia l'agente di Commercio conversazionale sia il filtro conversazionale dei prodotti, assicurati che il tuo ConversationalSearchRequest includa questa configurazione:

Richiesta API Conversational Commerce - Query iniziale

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

Le configurazioni chiave sono:

• Conversational_filtering_mode: ENABLED: se imposti questo campo su ENABLED in conversationalFilteringSpec, l'API viene informata che il tuo sistema è in grado di gestire il filtro conversazionale dei prodotti, consentendo all'API di fornire risposte specifiche per il filtro pertinenti.

Risposta iniziale: perfezionamento dell'intent

Il campo userQueryTypes rimane fondamentale per comprendere l'intent dell'utente. Per una query iniziale generica come Aiutami a organizzare una festa,l'API probabilmente la classificherà come INTENT_REFINEMENT se non è immediatamente chiara una ricerca di prodotto più specifica.

Risposta di Google

Risposta dell'API Conversational Commerce - Query iniziale

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

Azione

1. Visualizza conversationalTextResponse.
2. Presenta i refinedSearch suggerimenti come chip cliccabili per Decorazioni, Snack. In alternativa, chiama l'API Commerce Search in parallelo utilizzando le query refined_search per visualizzare risultati di prodotto pertinenti, ad esempio per Decorazioni, Snack come carosello, insieme allo scambio conversazionale.
3. Visualizza followupQuestion: Che tipo di festa stai organizzando?
4. Consente l'input utente in formato libero per far avanzare la conversazione.

Tagging degli eventi e analisi

Per garantire analisi e attribuzione accurate per l'interazione iniziale della conversazione:

• Recupera conversation_id. Acquisisci conversation_id da ConversationalSearchResponse. Questo ID è fondamentale per collegare tutte le azioni successive a questa sessione conversazionale specifica.
• Tagga gli eventi utente. Se la risposta conversazionale porta a una query di ricerca, ad esempio se il sistema esegue automaticamente una ricerca in base a una query refined_search o se l'utente fa clic su un suggerimento refined_search, devi taggare l'evento utente di ricerca successivo (UserEvent) con lo stesso conversation_id.

Query di follow-up

Quando l'utente risponde al followupQuestion, la conversazione viene perfezionata.

Input utente di esempio: Una festa di compleanno

Perfezionamento dell'intent | Snippet di codice

Richiesta API Conversational Commerce - Query di follow-up

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

Risposta dell'API Conversational Commerce - Query di follow-up

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

Azione

1. Come per la risposta iniziale, aggiorna l'interfaccia web con i nuovi conversationalTextResponse, i suggerimenti per refinedSearch e followupQuestion.
2. Continua il flusso della conversazione, chiedendo maggiori dettagli.

Tagging degli eventi e analisi

Quando l'utente continua la conversazione:

• Recupera conversation_id. Assicurati che il conversation_id del precedente ConversationalSearchResponse venga passato nel ConversationalSearchRequest corrente.
• Tagga gli eventi utente. Se la risposta conversazionale porta a una nuova query di ricerca, ad esempio perché un utente fa clic su un suggerimento refined_search o perché il sistema effettua una chiamata di ricerca parallela, tagga l'evento utente di ricerca successivo (UserEvent) con lo stesso conversation_id. Ciò consente di monitorare il percorso conversazionale a più turni.

Transizione al filtro conversazionale dei prodotti

Man mano che la conversazione diventa più specifica, il sistema potrebbe classificare l'intent come SIMPLE_PRODUCT_SEARCH e, se opportuno, attivare il filtro conversazionale dei prodotti.

Esempio di input dell'utente: tema delle principesse

Richiesta API Conversational Commerce - Query di follow-up

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

Possibili risultati per la ricerca di prodotti principali

Quando una query viene classificata come SIMPLE_PRODUCT_SEARCH, esistono due possibili risposte API, a seconda che venga attivato il filtro conversazionale dei prodotti. La differenza principale risiede nella presenza e nel contenuto del campo conversationalFilteringResult.

Risultato 1: il filtro viene attivato

Ciò si verifica quando la query è sufficientemente generica da poter essere ulteriormente perfezionata in base agli attributi del prodotto. La risposta include conversationalFilteringResult, a cui l'interfaccia web deve dare la priorità.

Risposta dell'API Conversational Commerce - Transizione al filtro dei prodotti:

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

Azione

La query è ora classificata come SIMPLE_PRODUCT_SEARCH. In questo caso, attiva il filtro conversazionale dei prodotti. Tuttavia, potrebbe non attivare il filtro conversazionale dei prodotti.

• Dai la priorità all'interfaccia web di filtraggio dei prodotti conversazionale:quando conversationalFilteringResult viene compilato, indica che hai attivato la modalità di filtraggio dei prodotti. L'interfaccia web deve mettere in evidenza followupQuestion, che nell'interfaccia utente appare come Che tipo specifico di decorazione da principessa stai cercando?, e suggestedAnswers, ad esempio pulsanti cliccabili per Palloncini, Festoni, Tovaglie.
• Visualizza i risultati dei prodotti: chiama immediatamente l'API Retail Search utilizzando refined_search.query (decorazioni per il compleanno di una principessa) per visualizzare i risultati iniziali dei prodotti insieme alle opzioni di filtro.
• Pratica consigliata per l'esperienza utente: deve essere presente una singola barra di input di testo libero persistente per l'intera esperienza. Questa barra rimane attiva in qualsiasi momento, anche durante un flusso di filtraggio conversazionale dei prodotti. Quando conversationalFilteringResult è attivo e mostri le risposte suggerite come chip cliccabili, gli utenti hanno due opzioni chiare:
• Continua il flusso di filtraggio facendo clic su una risposta suggerita.
• Avvia una nuova conversazione digitando una nuova query nella barra di testo attiva. Questo nuovo input attiva sempre una nuova chiamata all'API Conversational Commerce, terminando di fatto il flusso di filtraggio corrente.

Nota:questa scelta di progettazione è in linea con il principio fondamentale secondo cui l'input di testo libero viene gestito dall'API Conversational Commerce, mentre i clic sulle risposte suggerite vengono gestiti dal filtro conversazionale dei prodotti.

Risultato 2: non viene attivato alcun filtro

Se la query è già sufficientemente specifica o non si presta a ulteriori filtri, la risposta non include il campo conversationalFilteringResult. In questo caso, devi procedere con una ricerca standard.

Azione

• Considera l'interazione come la fine del flusso conversazionale e utilizza la query refined_search per chiamare l'API Retail Search e visualizzare una pagina standard dei risultati dei prodotti.

Tagging degli eventi e analisi

Quando la conversazione passa al filtro dei prodotti:

• Recupera conversation_id. Continua a utilizzare lo stesso conversation_id.
• Tagga gli eventi utente. Se la transizione porta a una ricerca immediata, tagga UserEvent con conversation_id. È importante sottolineare che quando l'utente interagisce con suggestedAnswers, ad esempio quando un utente finale fa clic su Palloncini, questa azione deve attivare anche un UserEvent, ad esempio un evento filter o un nuovo evento search, contrassegnato con lo stesso conversation_id. Ciò consente l'attribuzione delle azioni di filtraggio all'interno del flusso conversazionale.

Continua con il filtro conversazionale dei prodotti

Quando l'utente seleziona un suggestedAnswer, invia un nuovo ConversationalSearchRequest.

Esempio di input utente (clic su una risposta suggerita): Palloncini

Ricerca semplice di prodotti | Snippet di codice

Richiesta API Conversational Commerce - Continua a filtrare

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

Risposta dell'API Conversational Commerce: continua a filtrare

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

Azione

L'API risponde con una query SIMPLE_PRODUCT_SEARCH, ma senza il campo conversationalFilteringResult, a indicare che il flusso di filtri guidati è terminato.

• Utilizza la query finale refinedSearch (palloncini per il compleanno della principessa) per effettuare una chiamata diretta all'API Retail Search.
• Mostra all'utente i risultati finali del prodotto. A questo punto, la conversazione può terminare oppure l'utente può inserire una nuova query per iniziare un nuovo turno.

Tagging degli eventi e analisi

Per ogni passaggio del processo di filtraggio dei prodotti:

• Recupera conversation_id. Utilizza sempre lo stesso conversation_id per tutte le richieste all'interno della sessione di filtraggio.
• Tagga gli eventi utente. Ogni interazione dell'utente con un suggestedAnswer, ad esempio un clic, deve attivare un UserEvent pertinente, ad esempio un evento filter o un nuovo evento search se viene formata una nuova query. Questo UserEvent deve essere taggato con conversation_id per monitorare con precisione il percorso di filtraggio e il suo impatto sulla conversione.

Consigli sull'interfaccia utente e scelte di progettazione

L'interazione tra l'agente di Commercio conversazionale e il filtro conversazionale dei prodotti offre una flessibilità significativa. Ecco alcune considerazioni chiave sull'esperienza utente per creare un'esperienza fluida e intuitiva:

• Singola barra di input: deve essere presente una sola barra di input di testo libero per l'intera esperienza. Non esiste una barra di input separata e dedicata per il filtro conversazionale dei prodotti. In questo modo l'interfaccia utente viene semplificata e l'interazione rimane coerente.
• Transizioni fluide: progetta l'interfaccia web in modo che le transizioni tra le risposte conversazionali, le query suggerite e le opzioni di filtro risultino naturali e intuitive.
• Indicazioni chiare: utilizza segnali visivi come stili di pulsanti distinti per le risposte suggerite anziché input generici e istruzioni chiare per guidare l'utente su come interagire in ogni fase.
• Equilibrio del controllo: l'utente deve sempre sentirsi in controllo della direzione della conversazione.
• Filtro e formato libero: la singola barra di input di testo libero rimane attiva in qualsiasi momento. In questo modo, l'utente ha una scelta costante: può fare clic su una risposta suggerita per continuare a perfezionare la ricerca o digitare una nuova query nella barra di testo per iniziare un nuovo turno di conversazione. Questo design garantisce che, anche durante un flusso di filtraggio, l'utente possa passare a un altro argomento se le sue esigenze cambiano.
• Opzione di reimpostazione: fornisci un'opzione chiara Avvia nuova conversazione o Reimposta filtri per consentire agli utenti di riavviare la ricerca o la procedura di filtraggio.
• Persistenza visiva: anche durante la transizione al filtro dei prodotti, il mantenimento della cronologia delle conversazioni all'interno della finestra della chat, ad esempio la visualizzazione di domande e risposte precedenti, può migliorare il contesto e l'esperienza utente.

Ulteriori considerazioni e best practice

Quando implementi l'interfaccia dell'agente Conversational Commerce, devi prendere in considerazione ulteriori aspetti e best practice:

• Coerenza dell'ID visitatore: contribuisci a garantire che un visitor_id univoco venga inviato in modo coerente con ogni richiesta per un determinato utente finale. Questo è fondamentale per una personalizzazione e un addestramento del modello accurati. Idealmente, questo identificatore dovrebbe rimanere coerente per un utente finale in tutte le sessioni e gli stati di accesso o disconnessione.
• Gestione filiali: anche se default_branch è comune, assicurati di utilizzare l'ID filiale corretto se il catalogo prodotti è strutturato con più filiali.
• Interazione con l'API Search: per SIMPLE_PRODUCT_SEARCH e per tutti i casi in cui viene fornito refined_search, ricorda di effettuare una chiamata separata all'API Search principale (SearchService.Search) utilizzando query dal campo refined_search o la query originale per ottenere le schede di prodotto effettive. L'API conversazionale si concentra principalmente sull'esperienza conversazionale e sulla comprensione dell'intent dell'utente, anziché restituire direttamente i risultati dei prodotti.
• Progettazione dell'interfaccia utente: progetta l'interfaccia web in modo da presentare chiaramente le opzioni conversational_text_response, followup_question e refined_search in modo intuitivo per guidare l'utente.

Passaggi successivi

Per ulteriori risorse di supporto, consulta le domande frequenti sulle funzionalità conversazionali.