Token di attribuzione

I token di attribuzione sono ID univoci generati da Vertex AI Search per il commercio e restituiti con ogni richiesta di ricerca. Consentono a Vertex AI Search for Commerce di associare una richiesta di ricerca all'evento di ricerca corrispondente, il che consente ai modelli di ranking di migliorare la qualità delle risposte di ricerca. I token di attribuzione sono obbligatori anche negli eventi di ricerca di Vertex AI Search per il commercio per generare report accurati.

Come funzionano i token di attribuzione

Raccogli il attributionToken dalla risposta dell'API della ricerca di un utente. Restituire il token generato dal visitatore da quell'interazione specifica negli eventi utente.

Comportamento dei token di attribuzione

I token di attribuzione sono:

  • Specifico per visitatore: attributionToken è associato a una risposta di ricerca specifica pubblicata per un determinato visitorId. Pertanto, il token che hai ricevuto nella risposta a una ricerca effettuata da visitorId 'A' deve essere inviato di nuovo con gli eventi successivi provenienti dallo stesso visitorId 'A' che sono una conseguenza diretta di quella ricerca.

  • Associato agli eventi che seguono direttamente la ricerca: il valore attributionToken è particolarmente importante per gli eventi utente che rappresentano un'interazione diretta con i risultati di ricerca di quella ricerca specifica.

    È incluso quanto segue:

    • Eventi di ricerca successivi: se lo stesso utente esegue un'altra ricerca subito dopo quella iniziale (ad esempio per perfezionare la query), l'attributo attributionToken della prima risposta di ricerca dovrebbe idealmente essere incluso nell'evento utente per la seconda ricerca se questa è una continuazione della prima.
    • Eventi di visualizzazione della pagina dei dettagli: quando l'utente fa clic su un prodotto nei risultati di ricerca e ne visualizza i dettagli, il attributionToken della risposta alla ricerca che conteneva il prodotto deve essere incluso nell'evento utente di visualizzazione della pagina dei dettagli. Spesso questo viene fatto passando attributionToken come parametro URL alla pagina del prodotto.
    • Eventi di aggiunta al carrello: se l'utente aggiunge un prodotto al carrello direttamente dai risultati di ricerca o dopo aver visualizzato i dettagli di un prodotto trovato tramite quella ricerca, il valore attributionToken della risposta alla ricerca di origine deve essere incluso nell'evento add-to-cart.
    • Eventi di completamento dell'acquisto: se si sono verificate interazioni intermedie già attribuite, come le azioni detail-page-views o add-to-cart, attributionToken non viene inviato con l'evento purchase-complete. L'acquisto è ancora collegato tramite gli ID prodotto e visitorId.

  • Facilitare la mappatura delle richieste e degli eventi di ricerca: l'inclusione di attributionToken negli eventi utente successivi è fondamentale per mappare con precisione il comportamento dell'utente alla richiesta di ricerca specifica e ai relativi risultati pubblicati da Vertex AI Search for Commerce.

    Questo collegamento consente a Vertex AI Search di comprendere:

    • Quali query di ricerca e risultati hanno generato il coinvolgimento degli utenti (clic, visualizzazioni, aggiunte al carrello, acquisti).
    • La pertinenza e l'efficacia del ranking nei risultati di ricerca.
    • Indica se generare o meno esempi positivi e negativi per l'addestramento del modello di ranking.
    • Come calcolare le metriche per ricerca, come la percentuale di clic (CTR), il tasso di conversione (CVR) e le entrate per ricerca.
    • Come attribuire le conversioni alla ricerca specifica che le ha generate, in particolare negli scenari di test A/B.

Token di attribuzione nell'API Search

Ogni risposta restituita dal metodo Vertex AI Search per il commercio include un attributionToken univoco alla fine del corpo della risposta di ricerca. Ad esempio:

{
  "results": [
    {
      "id": "727121",
      "product": {
…
     }
  ],
  "totalSize": 19600,
  "attributionToken": "dfB0CgwIgKrltAYQ8afX4AIQARokNjZjMGEwYjEtMDAwMC0yNjAyLTk0Y2UtNTgyNDI5Y2JkMzUwKgUxMjM0NTIkxcvzF6OAlyLo5KotmNa3LY6-nRW3t4wtwvCeFdSynRWb1rctOg5kZWZhdWx0X3NlYXJjaGgB",
  "nextPageToken": "AM1MDZiNWOyQjM4UTLlNGN50iMwYjMtADMwATLwIGMhBzY2YDJaIw-bCbxQYAt1PJgIwgExEgC"
…

Questo token deve essere incluso nell'evento di ricerca successivo:

{
"eventType": "search",
"searchQuery":"red t-shirt", 
"productDetails":[
  {"product":{"id":"727121"}}, {"product":{"id":  …
  }
] ,
"visitorId":"GA1.1.1383176924.1721324981",
"attributionToken":"dfB0CgwIgKrltAYQ8afX4AIQARokNjZjMGEwYjEtMDAwMC0yNjAyLTk0Y2UtNTgyNDI5Y2JkMzUwKgUxMjM0NTIkxcvzF6OAlyLo5KotmNa3LY6-nRW3t4wtwvCeFdSynRWb1rctOg5kZWZhdWx0X3NlYXJjaGgB"
}

Vertex AI Search for Commerce utilizza i dati sugli eventi per addestrare i suoi modelli. Il token di attribuzione fornisce un modo per collegare l'evento alla richiesta, codificando la richiesta e la risposta di ricerca completa con i filtri, i facet e gli ID prodotto di risposta richiesti. Se non è presente un token negli eventi di ricerca, questi vengono trattati come se non provenissero da Vertex AI Search di Google e potrebbero essere utilizzati in modo errato come se provenissero da un altro fornitore di servizi di ricerca.

È normale (e previsto) che gli eventi di ricerca non contengano token se vengono pubblicati da un altro fornitore di servizi di ricerca, ad esempio durante un esperimento A/B. Tuttavia, in genere esiste una mappatura 1:1 per le richieste dell'API di ricerca per cercare eventi con token.

Effetto negativo dei token mancanti

Se attributionToken non è presente negli eventi utente successivi pertinenti dello stesso visitatore, Vertex AI Search for Commerce tratta questi eventi come se non fossero stati originati dal suo servizio di ricerca.

Ciò può comportare:

  • Addestramento del modello non accurato.
  • Metriche e analisi delle prestazioni errate.
  • Potenziali problemi con il raggiungimento di livelli di rendimento più elevati (come il livello 3) che richiedono eventi attribuibili sufficienti.
  • Errori segnalati nella dashboard della qualità dei dati nella Ricerca per il commercio se la percentuale di eventi con token di attribuzione è inferiore al 95%.

Per apprendere dal comportamento degli utenti e ottimizzare i risultati di ricerca, Vertex AI Search for Commerce richiede un'attribuzione accurata. Assicurati che attributionToken di una risposta di ricerca sia associato al visitatore specifico che ha effettuato la ricerca. Deve essere presente negli eventi utente generati dall'interazione di ricerca, in particolare per gli eventi search, detail-page-view e add-to-cart.

Qualità dei dati dei token di attribuzione

La dashboard della qualità dei dati nella console Ricerca per il commercio mostrerà uno stato di errore di mancata conformità critico o di blocco se la percentuale di eventi con token di attribuzione è inferiore al 95%. In caso contrario, lo stato sarà Conforme:

Testo alternativo

In genere, la qualità dei dati di Livello 3, ovvero il modello ottimizzato per le entrate, non viene addestrata senza eventi attribuibili sufficienti. Sconsigliamo vivamente di eseguire il deployment di Vertex AI Search for Commerce in produzione, a meno che non vengano pubblicati risultati di livello 3 o 4. Per saperne di più, consulta la sezione Qualità dei dati su come sbloccare i livelli di rendimento nella pagina Qualità dei dati di questa documentazione.

Token di attribuzione per i consigli

Poiché non esiste un evento utente specifico per i consigli, non includere i token di attribuzione delle risposte predict in nessun evento. Tuttavia, ti consigliamo vivamente di includere PredictResponse.attribution_token negli eventi utente successivi derivanti da un consiglio (ad esempio detail-page-view o add-to-cart).

L'implementazione richiede il passaggio del token di attribuzione del prodotto consigliato in un parametro URL all'URL pagina del prodotto. Poi, utilizza questo parametro per compilare il campo attributionToken dell'evento utente corrispondente.

I consigli di Vertex AI Search creano automaticamente token sintetici per gli eventi attribuibili alle richieste predict. L'aggiunta esplicita dei token può migliorare leggermente l'accuratezza dei report di analisi. Tuttavia, non è strettamente necessario e avrà scarso impatto sui modelli di consigli.