Informazioni sugli eventi utente

Questa pagina descrive l'oggetto evento utente, inclusi i potenziali tipi di eventi utente, e fornisce dati di esempio per tutti i tipi di eventi utente.

Vertex AI Search per il commercio utilizza gli eventi utente in tempo reale per generare suggerimenti e risultati di ricerca. Quando carichi i dati, sia i consigli sia la ricerca possono utilizzarli, quindi non devi caricare due volte gli stessi eventi se utilizzi entrambi i servizi.

Come funziona l'attribuzione della ricerca

Come funziona l'attribuzione

Panoramica dei tipi di eventi utente

Esistono diversi tipi di eventi utente che puoi registrare mentre gli utenti navigano nel tuo sito di vendita al dettaglio:

Nome evento utente Azione dell'utente Google Analytics 4 event_name
home-page-view Visualizza la home page. view_homepage
search (Cerca e sfoglia) Cerca nel catalogo. view_item_list + [searchQuery O pageCategories + filter]
category-page-view (solo consigli) Visualizza pagine speciali, come quelle di vendite o promozioni. view_item_list + pageCategories
detail-page-view Visualizza la pagina dei dettagli del prodotto. view_item
add-to-cart Aggiunge il prodotto al carrello. add_to_cart
shopping-cart-page-view Visualizza il carrello degli acquisti. begin_checkout
purchase-complete Completa il pagamento. purchase

Tra questi tipi di eventi, Vertex AI Search for commerce utilizza in modo specifico questi quattro per l'indicazione della popolarità:

  • SEARCH
  • DETAIL_PAGE_VIEW
  • ADD_TO_CART
  • PURCHASE_COMPLETE

Per un elenco completo dei campi evento GA4, consulta Campi evento utente di Google Analytics 4.

Per informazioni dettagliate sull'oggetto UserEvent, consulta UserEvent.

Requisiti per gli eventi utente

Le tabelle seguenti elencano i requisiti e le best practice per i tipi di eventi utente utilizzati dai suggerimenti e dalla ricerca. Verifica che gli eventi utente soddisfino questi requisiti in modo che Vertex AI Search for Commerce possa generare risultati di qualità.

Questa sezione elenca:

Se utilizzi modelli per i suggerimenti, consulta anche Requisiti dei dati per tipo di modello, che elenca requisiti aggiuntivi a seconda del tipo di modello per i suggerimenti e dell'obiettivo di ottimizzazione che prevedi di utilizzare.

Puoi visualizzare le metriche sulla qualità dei dati per la ricerca nella pagina Qualità dei dati della console Search for commerce. Queste metriche mostrano le percentuali di prodotti ed eventi utente che soddisfano gli standard consigliati di qualità dei dati. Per informazioni su come visualizzare la qualità dei dati di ricerca, vedi Sbloccare i livelli di rendimento della ricerca.

Requisiti generali per gli eventi utente

Assicurati che gli eventi utente soddisfino i seguenti requisiti in modo che Vertex AI Search per il commercio possa generare risultati di qualità. Queste si applicano sia ai consigli sia alla ricerca.

Tipo di evento Requisito Impatto
Tutti gli eventi

Non includere dati sintetici o eventi duplicati.

Gli eventi sintetici o duplicati influiscono negativamente sulla qualità del modello e spesso impediscono l'addestramento del modello. Gli eventi duplicati possono causare valori delle metriche errati.

Includi almeno 100 ID visitatore unico per ogni tipo di evento inserito.

In questo modo si verifica che Vertex AI Search for commerce disponga di dati sufficienti per generare risultati di qualità.

Gli ID visitatore devono essere formattati esattamente allo stesso modo nell'importazione o nella registrazione degli eventi e nelle richieste API.

L'utilizzo di un formato coerente per gli ID visitatore consente di identificare correttamente i modelli dei visitatori e fornire risultati di qualità migliore in base al comportamento degli utenti.

I prodotti inclusi negli eventi devono esistere nel tuo catalogo di prodotti.

Il rapporto tra eventi non uniti deve essere mantenuto il più basso possibile. Un rapporto elevato può influire negativamente sulla qualità dei risultati di ricerca o dei consigli.

I dati sugli eventi non associati non vengono utilizzati per addestrare i modelli. Tuttavia, gli eventi non associati possono essere associati in un secondo momento, dopo l'importazione dei prodotti associati. Per saperne di più, vedi Ricongiungere gli eventi utente.

Alcuni eventi utente devono avere lo stesso ID visitatore.

Per creare cronologie valide delle sequenze di comportamenti, Vertex AI Search for commerce deve essere in grado di visualizzare più eventi con lo stesso ID visitatore.

Ad esempio, visitor123 ha visualizzato cinque pagine dei dettagli prodotto, ha aggiunto tre prodotti al carrello e poi ha acquistato due dei cinque prodotti originali. Se questi eventi forniscono tutti lo stesso ID visitatore con una formattazione coerente, Vertex AI Search for commerce può prendere in considerazione questa sequenza di comportamenti nei suoi modelli.

detail-page-view

Includi esattamente un prodotto per evento.

L'evento non può essere utilizzato se non esiste alcun prodotto. Se sono inclusi più prodotti, l'evento è malformato e non può essere utilizzato.

add-to-cart

Includi esattamente un prodotto per evento.

Se sono inclusi più prodotti, l'evento è malformato e non può essere utilizzato.

purchase-complete

Includi purchase_transaction.revenue.

Gli eventi purchase-complete a cui manca il campo revenue non vengono utilizzati per addestrare i modelli.

Includi esattamente un purchase_transaction.currency_code in tutti gli eventi di acquisto.

Non è presente un codice valuta predefinito, pertanto è necessario fornirne uno.

Gli eventi di acquisto senza questo campo generano metriche errate per le entrate.

Verifica che alcuni eventi di acquisto includano più prodotti.

La presenza di alcuni eventi di acquisto con più prodotti aiuta il modello ad apprendere i pattern di acquisto congiunto.

Requisiti specifici per i consigli

Se utilizzi i consigli, assicurati che gli eventi utente soddisfino i seguenti requisiti.

Se utilizzi modelli per i suggerimenti, consulta anche Requisiti dei dati per tipo di modello, che elenca requisiti aggiuntivi a seconda del tipo di modello per i suggerimenti e dell'obiettivo di ottimizzazione che prevedi di utilizzare.

Tipo di evento Requisito Impatto
purchase-complete

Non appiattire i carrelli con più articoli in più eventi di acquisto. Devono rimanere come singoli eventi di acquisto che includono più prodotti.

In questo modo, vengono generati pattern di acquisto congiunto validi.

Requisiti specifici per la ricerca

Se utilizzi la ricerca, assicurati che gli eventi utente soddisfino i seguenti requisiti minimi per ottenere risultati.

Tipo di evento Requisito Impatto
search

searchQuery deve esistere per gli eventi di ricerca e pageCategories deve esistere per gli eventi di navigazione.

Se non includi questo campo, la qualità e le metriche dei risultati di ricerca potrebbero risentirne negativamente.

L'ID visitatore nelle richieste di ricerca deve corrispondere all'ID visitatore inviato negli eventi correlati a quella richiesta di ricerca.

Se non corrispondono, gli eventi sono malformati e le metriche potrebbero essere errate.

L'elenco degli ID prodotto negli eventi di ricerca deve corrispondere all'elenco dei prodotti mostrati all'utente nella sua interezza.

Se non corrispondono, l'impatto negativo sulla qualità dei risultati di ricerca può essere grave e le metriche saranno errate.

Se la ricerca utilizza un filtro, filter deve esistere ed essere analizzato correttamente.

Se questo campo non esiste, Vertex AI Search for Commerce non può utilizzare la parte di filtro dei dati, il che può influire negativamente sulla qualità dei risultati di ricerca.

Includi il campo attribution_token per collegare altri eventi agli eventi di ricerca.

Se non includi un token di attribuzione, si verificherà un errore nella ricerca per il commercio e la qualità della ricerca e l'accuratezza delle metriche ne risentiranno negativamente.

Requisiti per l'ottimizzazione della ricerca

Per consentire alla ricerca di ottimizzare automaticamente l'esperienza di ricerca in base alle tendenze generali degli utenti, carica i seguenti dati.

Gli eventi devono essere caricati almeno una volta al giorno con un ritardo massimo di 24 ore.

Metrica Eventi Volume/frequenza degli eventi Descrizione
Volume di eventi search 250.000 negli ultimi 90 giorni

Per ottimizzare l'esperienza di ricerca in base agli eventi importati,sono necessari almeno 250.000 eventi negli ultimi 90 giorni.

Per mantenere una buona qualità dei dati, ti consigliamo di caricare gli eventi almeno una volta al giorno. Durante le importazioni di eventi storici, assicurati che la distribuzione dei dati sia sbilanciata verso il timestamp più recente. Il numero di eventi nell'ultimo giorno del timestamp deve essere uguale o superiore al conteggio medio giornaliero degli eventi.
Volume di detail-page-view attribuito a un evento search 500.000 negli ultimi 30 giorni Per ottimizzare i risultati di ricerca utilizzando gli eventi utente sono necessari almeno 500.000 eventi.
Media di eventi detail-page-view attribuibili a un evento search per prodotto 10 negli ultimi 30 giorni Obbligatorio per ottimizzare i risultati di ricerca utilizzando gli eventi inseriti, a meno che non vengano caricati gli eventi degli ultimi 21 giorni.
Proporzione di eventi search con filtri analizzabili 0,1 negli ultimi 30 giorni Consigliato per ottimizzare l'ordine dei facet dinamici nella risposta della ricerca.
Proporzione di prodotti cercati con prezzo 0,95 negli ultimi 30 giorni Obbligatorio per ottimizzare i risultati di ricerca utilizzando gli eventi inseriti.
Media di eventi add-to-cart attribuibili a un evento search per prodotto a pagamento 0,5 negli ultimi 30 giorni Consigliato per risultati di ricerca ottimizzati per le entrate.
Media di eventi purchase-complete attribuibili a un evento search per prodotto a pagamento ricercabile 0,5 negli ultimi 30 giorni Consigliato per i risultati di ricerca ottimizzati per le entrate.

Requisiti per la Ricerca personalizzata

La ricerca richiede i seguenti dati per personalizzare la ricerca di testo e sfogliare i risultati di ricerca per gli utenti in base alla loro attività.

Dopo aver caricato i seguenti dati, la ricerca può personalizzare automaticamente i risultati.

Metrica Eventi Volume/frequenza degli eventi Descrizione
Volume di eventi search gestiti dalla ricerca 100.000 negli ultimi 30 giorni

Per fornire la personalizzazione,sono necessari almeno 100.000 eventi gestiti dalla ricerca negli ultimi 30 giorni.

I risultati di ricerca non vengono memorizzati nella cache Meno dell'1% degli ultimi 100.000 eventi utente

Non memorizzare nella cache i risultati di ricerca per la ricerca di testo o la navigazione se prevedi di utilizzare la personalizzazione. Il riutilizzo degli stessi risultati per tutti i visitatori impedisce alla ricerca di fornire risultati veramente personalizzati a un determinato utente e rischia di esporre i dati privati degli utenti. La personalizzazione della Ricerca viene disattivata automaticamente se viene rilevata la memorizzazione nella cache.

Se memorizzi nella cache solo i risultati di ricerca, la ricerca può comunque personalizzare i risultati della navigazione. Al contrario, se memorizzi nella cache solo i risultati di navigazione, la ricerca può comunque personalizzare i risultati di ricerca delle query di testo.

Corrispondenze tra ID visitatore e eventi utente di SearchRequests Corrispondenza superiore al 10% per gli ultimi 100.000 eventi utente Assicurati che la spaziatura e la formattazione dell'ID visitatore corrispondano in SearchRequests e negli eventi utente. La formattazione coerente dell'ID visitatore verifica che la ricerca possa identificare correttamente l&#39attività utenteà dell'utente.

Best practice per gli eventi utente

Questa sezione descrive le best practice per gli eventi utente in Vertex AI Search for commerce.

Controllo delle impressioni del prodotto

Quando inserisci eventi in Vertex AI Search per eventi storici di e-commerce o eventi live di produzione, assicurati che vengano rispettati i seguenti limiti per l'addestramento del modello, come descritto qui.

È importante notare che il volume minimo di eventi richiesto non è un numero di volume generico. Ad esempio, se i limiti indicano che sono necessari 150.000 eventi di visualizzazione della pagina dei dettagli, non devi pensare che si tratti di 150.000 eventi casuali di visualizzazione della pagina dei dettagli. Gli eventi devono essere correlati ad altri eventi come SEARCH o ADD TO CART.

Il modello viene addestrato sugli eventi, in particolare per l'ottimizzazione del tasso di clic, sugli eventi SEARCH e sul successivo evento di visualizzazione della pagina dei dettagli. In effetti, ogni evento di visualizzazione della pagina dei dettagli deve essere riconducibile a un elenco di ID prodotto dell'evento di ricerca.

Lo stesso vale per gli eventi di aggiunta al carrello e di acquisto. In altre parole, se disegni una cronologia degli eventi utilizzando i timestamp degli eventi per un determinato ID visitatore, puoi dedurre un comportamento di ricerca, clic o acquisto. Pertanto, se trovi un evento di visualizzazione della pagina dei dettagli casuale che non è associato ad alcun evento di ricerca, questo evento non può essere utilizzato per l'addestramento del modello.

Assicurati quindi che gli eventi importati siano ricollegati a un evento di ricerca, il che significa che i timestamp, l'ID visitatore e i dettagli dell'ID prodotto devono essere accurati per l'addestramento del modello.

Priorità del tipo di evento

Per ottenere risultati di massima qualità, registra gli eventi utente per tutti i tipi di eventi. La tabella seguente descrive la priorità dei diversi tipi di eventi utente. Per ottenere modelli di dati di qualità, devi registrare gli eventi utente con la priorità più alta.

Priorità Tipi di eventi utente

Obbligatorio per la sperimentazione iniziale dal vivo per i consigli

(i tipi di evento dipendono dal tipo di modello di suggerimento)

detail-page-view

add-to-cart

purchase-complete

home-page-view
Evento aggiuntivo richiesto per l'esperimento live di ricerca

search

In base a questi eventi, Vertex AI Search for Commerce può determinare su quale prodotto è stato fatto clic, quale è stato aggiunto al carrello e quale è stato acquistato. In questo modo, il modello viene addestrato mentre il prodotto riceve più interazioni e conversioni, il che lo aiuterà a posizionarlo meglio per un aumento ottimizzato delle entrate.

A parte questo, gli eventi utente sono anche la base per la misurazione dei KPI, tra cui entrate per utente, CTR e CVR.

Per addestrare un modello basato sui dati storici generati dal motore di ricerca precedente, gli eventi utente devono essere inizialmente compilati a partire dai dati storici sul coinvolgimento del sito (in genere forniti da un framework di analisi del sito). Potresti dover trasformare gli eventi storici esistenti nello schema degli eventi utente prescritto per Vertex AI Search for Commerce. Queste informazioni sono necessarie per addestrare il modello all'ottimizzazione delle entrate. Dopo questo passaggio, gli eventi devono essere inviati continuamente a Vertex AI Search for Commerce utilizzando l'importazione collettiva o la raccolta.

Attribuzione degli eventi

Il flusso di sequenza degli eventi utente descrive il modo in cui gli utenti hanno eseguito le attività sul sito web.

Il flusso utente ideale è:

  1. L'utente esegue una ricerca su una query.

  2. L'utente esegue visualizzazioni di pagina sul prodotto di interesse.

  3. L'utente aggiunge al carrello il prodotto che intende acquistare.

  4. L'utente esegue una transazione di acquisto per i prodotti che decide di acquistare.

Allo stesso modo, gli eventi utente dovrebbero essere eseguiti con un pattern simile per un determinato ID visitatore. Ciò significa che, in una scala temporale, non può verificarsi un evento di aggiunta di un prodotto al carrello dopo una transazione di acquisto per un determinato ID visitatore per il prodotto acquistato.

Il flusso di eventi ideale è:

  • Percorso 1: evento di ricerca → evento di visualizzazione della pagina dei dettagli → evento di aggiunta al carrello → evento di acquisto
  • Percorso 2: evento di ricerca → evento Aggiungi al carrello → evento di acquisto

In una chiamata API di ricerca non memorizzata nella cache, il flusso di eventi è il seguente:

  • Ogni visitatore viene servito da una risposta di ricerca univoca e il rispettivo token di attribuzione viene inviato successivamente.
  • Esiste una chiara distinzione tra il monitoraggio di visitorID1 e visitorID2, poiché il token di attribuzione è diverso.

Esempi e schemi di tipi di eventi utente

Questa sezione fornisce i formati dei dati per ogni tipo di evento supportato.

Vengono forniti esempi per il pixel JavaScript e Tag Manager. Per BigQuery, viene fornito lo schema completo della tabella per ogni tipo.

Per tutti i tipi di eventi utente, userId è facoltativo. I campi delle informazioni sul prodotto (priceInfo e availability) sono facoltativi.

Ricorda:

  • Il campo experimentIds è necessario solo se stai eseguendo un esperimento A/B.
  • Il campo attributionToken è obbligatorio solo per Vertex AI Search for commerce. Viene utilizzato per misurare il rendimento. I token di attribuzione non devono essere inviati a predict, search e detail-page-view o agli eventi di clic.
  • Assicurati che tutti gli eventi utilizzino una singola valuta, soprattutto se prevedi di utilizzare la consoleGoogle Cloud per ottenere le metriche sulle entrate. L'API Vertex AI Search for Commerce non supporta l'utilizzo di più valute per catalogo.

Per ulteriori dettagli sull'oggetto evento utente, consulta la documentazione di riferimento dell'API UserEvent.

Aggiungi al carrello

Di seguito è riportato il formato dell'evento utente add-to-cart in un esempio che utilizza solo i campi obbligatori.

La quantità di prodotto in un evento add-to-cart deve essere un valore incrementale che rappresenta la quantità di prodotto associata a quello specifico evento utente. Ad esempio, se al carrello degli acquisti vengono aggiunte due unità di un prodotto, il campo della quantità per l'evento add-to-cart deve essere 2. Per gli eventi add-to-cart, includi esattamente un prodotto per evento.

Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Potrebbero essere necessari altri campi a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per tutti i dettagli su ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": { "value": product-quantity }
  }]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'add-to-cart',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }]
      }
    });
</script>

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Visualizzazione pagina delle categorie

Di seguito viene mostrato il formato dell'evento utente category-page-view.

Gli esempi seguenti mostrano solo i campi obbligatori del formato dell'evento utente category-page-view.

Anche se di solito a una pagina è associata una sola categoria, il campo pageCategories supporta anche una gerarchia di categorie, che puoi fornire come elenco.

Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Potrebbero essere necessari altri campi a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per tutti i dettagli su ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "category-page-view",
  "visitorId": "visitor-id",
  "pageCategories": ["category1 > category2"]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'category-page-view',
        'visitorId": 'visitor-id',
        // You can also define the user ID and visitor ID
        // directly on the Tag Manager tag.
        'pageCategories': ['category1 > category2']
      }
    });
</script>

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Visualizzazione pagina dei dettagli

Di seguito è riportato il formato dei dati sugli eventi utente detail-page-view.

Gli esempi seguenti mostrano solo i campi obbligatori del formato dell'evento utente detail-page-view.

Nella maggior parte dei casi, productDetails contiene i dettagli del prodotto associato, a meno che non venga venduto un bundle di articoli insieme.

Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Potrebbero essere necessari altri campi a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per tutti i dettagli su ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "detail-page-view",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    }
  }]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'detail-page-view',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          }
        }]
      }
    });
</script>

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Visualizzazione home page

Di seguito viene mostrato il formato dell'evento utente home-page-view.

Gli esempi seguenti mostrano solo i campi obbligatori del formato dell'evento utente home-page-view.

Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Potrebbero essere necessari altri campi a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per tutti i dettagli su ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "home-page-view",
  "visitorId": "visitor-id",
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'home-page-view',
        'visitorId': 'visitor-id'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
      }
    });
</script>

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Acquisto completato

Di seguito è riportato il formato dei dati sugli eventi utente purchase-complete.

Gli esempi seguenti mostrano solo i campi obbligatori del formato dell'evento utente purchase-complete.

Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Potrebbero essere necessari altri campi a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per tutti i dettagli su ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "purchase-complete",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": product-quantity
  }],
  "purchaseTransaction": {
    "revenue": revenue,
    "currencyCode": "currency-code"
  }
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'purchase-complete',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID directly on
        // the Tag Manager tag.
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }],
        'purchaseTransaction': {
          'revenue': revenue,
          'currencyCode': 'currency-code'
        }
      }
    });
</script>

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         },
         {
           "name": "priceInfo",
           "type": "RECORD",
           "mode": "NULLABLE",
           "fields": [
             {
               "name": "price",
               "type": "FLOAT",
               "mode": "REQUIRED"
             },
             {
               "name": "originalPrice",
               "type": "FLOAT",
               "mode": "NULLABLE"
             },
             {
               "name": "currencyCode",
               "type": "STRING",
               "mode": "REQUIRED"
             },
             {
               "name": "cost",
               "type": "FLOAT",
               "mode": "NULLABLE"
             }
           ]
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "purchaseTransaction",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "revenue",
       "type": "FLOAT",
       "mode": "REQUIRED"
     },
     {
       "name": "tax",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "cost",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "currencyCode",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Di seguito viene mostrato il formato dell'evento utente search.

Oggetto di ricerca minimo richiesto

Questi sono i campi minimi richiesti per Vertex AI Search for Commerce per restituire un elenco di risultati di ricerca:

  • searchQuery viene letto dal parametro search_term o dagli eventi view_search_results.
  • productDetails viene letto dal parametro items dell'evento view_item_list. Deve includere l'elenco degli ID prodotto mostrati all'utente finale nella pagina dei risultati di ricerca.
  • userEvents acquisisce tutte le informazioni sui metadati che l'API Retail deve conoscere su come gli utenti finali interagiscono con il sito web del cliente.

Gli esempi seguenti mostrano solo i campi obbligatori del formato dell'evento utente search.

Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Potrebbero essere necessari altri campi a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per tutti i dettagli su ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
      }
    });
</script>

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Completamento automatico

Questo campo è obbligatorio per gli eventi di ricerca solo se vuoi utilizzare il completamento automatico. Non è obbligatorio per la ricerca.

Gli esempi seguenti mostrano il campo completionDetail quando un utente digita "sc" e fa clic sul secondo suggerimento, "scarpe", nell'elenco dei suggerimenti per attivare un evento di ricerca. Se l'utente non fa clic su nessun suggerimento, il campo completionDetail rimane vuoto.

eventType deve essere "search".

completionAttributionToken è il attributionToken della risposta completeQuery.

selectedSuggestion deve essere uguale a searchQuery.

Pixel JavaScript

var user_event = {
  "eventType": "search",
  "visitorId": "visitor-id",
  "searchQuery": "search-query",
  "pageCategories": ["category1 > category2"],
  "productDetails": [
    {
      "product": {
        "id": "product-id1"
      }
    }, {
      "product": {
        "id": "product-id2"
      }
    }
  ]
  "completionDetail": {
    "completionAttributionToken": "completion_token",
    "selectedSuggestion": "search-query",
    "selectedPosition": completion_position
  }
};

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'search',
        'visitorId': 'visitor-id',
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'searchQuery': 'search-query',
        'pageCategories': ['category1 > category2'],
        'productDetails': [
          {
            'product': {
              'id': 'product-id1'
            }
          }, {
            'product': {
              'id': 'product-id2'
            }
          }
        ]
        "completionDetail": {
          "completionAttributionToken": 'completion_token',
          "selectedSuggestion": 'search-query',
          "selectedPosition": completion_position
        }
      }
    });
</script>

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "searchQuery",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "completionDetail",
   "type": "RECORD"
   "mode": "NULLABLE"
   "fields": [
     {
       "name": "completionAttributionToken",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedSuggestion",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedPosition",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
    ]
 }
]

Visualizzazione pagina del carrello degli acquisti

Di seguito è riportato il formato dei dati sugli eventi utente shopping-cart-page-view.

Gli esempi seguenti mostrano solo i campi obbligatori del formato dell'evento utente shopping-cart-page-view.

Fornisci gli oggetti productDetails e userEvents, a meno che il carrello non sia vuoto.

Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Potrebbero essere necessari altri campi a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per tutti i dettagli su ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "shopping-cart-page-view"",
  "visitorId": "VISITOR-ID"
  "cartId": "CART-ID",
  "productDetails": [{
      "product": {
        "id": "PRODUCT-ID"
      },
      "quantity": PRODUCT-QUANTITY
    }]
};

Sostituisci PRODUCT-ID, PRODUCT-QUANTITY, VISOTOR-ID e CART-ID con l'ID prodotto, la quantità di prodotto, l'ID sessione e l'ID carrello.

Tag Manager 

<script>
    dataLayer = dataLayer || [];
    dataLayer.push({
      'cloud_retail': {
        'eventType': 'shopping-cart-page-view',
        'visitorId': 'VISITOR-ID'
        // You can also define the visitor ID
        // directly on the Tag Manager tag.
        'cartId': 'CART-ID',
        'productDetails': [{
            'product': {
              'id': 'PRODUCT-ID'
            },
            'quantity': PRODUCT-QUANTITY
          }]
      }
    });
</script>

Sostituisci PRODUCT-ID, PRODUCT-QUANTITY, VISOTOR-ID e CART-ID con l'ID prodotto, la quantità di prodotto, l'ID sessione e l'ID carrello.

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "visitorId",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "eventTime",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Campi evento utente di Google Analytics 4

La tabella seguente mostra come i campi evento utente di Google Analytics 4 vengono mappati ai campi di Vertex AI Search for commerce.

Prima di importare o registrare gli eventi utente da Google Analytics 4, assicurati che utilizzino i seguenti campi in modo che Vertex AI Search for commerce possa integrare correttamente i tuoi dati.

Google Analytics 4 Vendita al dettaglio
ecommerce.purchase_revenue purchaseTransaction.revenue
event_name eventType
event_timestamp eventTime
items.item_id productDetails.product.id
items.price productDetails.product.priceInfo.price
items.quantity productDetails.quantity
Chiave:
event_params.key impostata su "currency"

Valore:
event_params.value.string_value		 productDetails.product.priceInfo.currencyCode
Chiave:
event_params.key impostata su "currency"

Valore:
event_params.value.string_value		 purchaseTransaction.currencyCode
Chiave:
event_params.key impostata su "search_term"

Valore:
event_params.value.string_value		 searchQuery
user_id userInfo.userId
user_pseudo_id visitorId

Passaggi successivi