Informazioni sugli eventi utente

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

Vertex AI Search for Retail utilizza 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 gli stessi eventi due volte se utilizzi entrambi i servizi.

Per assistenza sulla registrazione degli eventi utente, consulta: Registra gli eventi utente in tempo reale.

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
add-to-cart Aggiunge il prodotto al carrello.
category-page-view Visualizza pagine speciali, ad esempio pagine di saldi o promozioni.
detail-page-view Visualizza la pagina dei dettagli del prodotto.
home-page-view Visualizza la home page.
purchase-complete Completa il pagamento.
ricerca Cerca nel catalogo.
shopping-cart-page-view Visualizza il carrello degli acquisti.

Per informazioni dettagliate sull'oggetto UserEvent, consulta UserEvent.

Priorità del tipo di evento

Per risultati di qualità ottimale, ti consigliamo di registrare gli eventi utente per per tutti i tipi di eventi. La tabella seguente descrive la priorità delle diverse tipi di eventi utente. Devi registrare gli eventi utente con la massima priorità da raggiungere di dati di qualità.

Priorità Eventi utente
Obbligatorio per l'esperimento in corso iniziale

add-to-cart

detail-page-view

purchase-complete

home-page-view (per i consigli)

search (per la ricerca)
Importante per migliorare la qualità del modello dei suggerimenti nel tempo

category-page-view

search

shopping-cart-page-view

Requisiti e best practice per gli eventi utente

Le seguenti tabelle elencano i requisiti e le best practice per i tipi di eventi utente usate dai consigli e dalle ricerche. Verifica che i tuoi eventi utente soddisfino questi requisiti affinché Vertex AI Search per il retail possa generare risultati di qualità.

Questa sezione elenca:

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

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

Requisiti per gli eventi utente

Assicurati che gli eventi utente soddisfino i seguenti requisiti, in modo che Vertex AI Search for Retail può generare risultati di qualità. Queste norme 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 ne impediscono il corretto addestramento. Gli eventi duplicati possono causare valori delle metriche errati.

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

In questo modo, Vertex AI Search per il retail dispone di dati sufficienti per generare risultati di qualità.

Gli ID visitatore devono essere formattati nello stesso modo in tutta l'importazione dell'evento. o la registrazione di eventi e nelle richieste API.

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

I prodotti inclusi negli eventi devono essere presenti nel tuo catalogo di prodotti di big data e machine learning.

Il rapporto tra eventi non uniti deve essere mantenuto il più basso possibile. Una può influire negativamente sulla qualità dei suggerimenti o della ricerca che consentono di analizzare i dati e visualizzare i risultati.

I dati sugli eventi non associati non vengono utilizzati per addestrare i modelli. Tuttavia, gli utenti non iscritti è possibile partecipare in un secondo momento, dopo che i prodotti associati importati. Per ulteriori informazioni, vedi Eventi di riunione degli utenti.

Alcuni eventi utente devono avere lo stesso ID visitatore.

Per creare storie di sequenze di comportamento valide, Vertex AI Search per la vendita al dettaglio deve essere in grado di vedere più eventi con lo stesso ID visitatore.

Ad esempio, visitor123 ha visualizzato i dettagli di cinque prodotti pagine, ha aggiunto tre prodotti al carrello, poi ha acquistato due dei cinque prodotti originali. Se tutti questi eventi forniscono lo stesso ID visitatore con formato coerente, Vertex AI Search per la vendita al dettaglio può prendere in considerazione questa sequenza di comportamento nei suoi modelli.

detail-page-view

Includi esattamente un prodotto per evento.

L'evento non può essere utilizzato se non esiste alcun prodotto. Se vengono visualizzati più prodotti incluso, l'evento ha un formato non valido e non può essere utilizzato.

add-to-cart

Includi esattamente un prodotto per evento.

Se sono inclusi più prodotti, l'evento non è formato correttamente 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 un solo elemento purchase_transaction.currency_code a tutti gli eventi di acquisto.

Non esiste un codice valuta predefinito; è necessario fornire un codice.

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

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 combinato.

Requisiti specifici dei consigli

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

Se utilizzi i modelli per i consigli, consulta anche Requisiti dei dati per il tipo di modello, che elenca i requisiti aggiuntivi a seconda del tipo di modello per i consigli 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. Loro devono rimanere come eventi di acquisto singolo che includono più prodotti.

In questo modo vengono generati pattern validi per l'acquisto in compagnia.

Requisiti di 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.

La mancata inclusione di questo campo può avere un grave impatto negativo sulla qualità e sulle metriche dei risultati di ricerca.

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

Se non corrispondono, il formato degli eventi non è corretto e le metriche potrebbero essere risposta errata.

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

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

Se la ricerca utilizza un filtro, filter deve esistere e essere analizzata correttamente.

Se questo campo non esiste, Vertex AI Search for Retail 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 torna agli eventi di ricerca.

La mancata inclusione di un token di attribuzione attiverà un errore in Search for Retail e avrà un grave impatto negativo sulla ricerca la qualità e l'accuratezza delle metriche.

Requisiti per l'ottimizzazione della ricerca

Per consentire alla ricerca di ottimizzare automaticamente l'esperienza di ricerca in base sulle 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 si distingua verso il timestamp più recente. Il numero di eventi dell'ultimo giorno timestamp deve essere uguale o superiore al conteggio medio degli eventi giornalieri.

Volume di detail-page-view attribuibile a un search evento 500.000 negli ultimi 30 giorni Per ottimizzare la ricerca sono obbligatori almeno 500.000 eventi usando gli eventi utente.
detail-page-view in media di eventi attribuibili a un search evento per prodotto 10 negli ultimi 30 giorni Obbligatorio per ottimizzare i risultati di ricerca utilizzando gli eventi acquisiti, 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 alla ricerca.
Proporzione di prodotti cercati con prezzo 0,95 negli ultimi 30 giorni Obbligatorio per ottimizzare i risultati di ricerca utilizzando gli eventi importati.
add-to-cart in media di eventi attribuibili a un search evento per prodotto a pagamento 0,5 negli ultimi 30 giorni Consigliato per i risultati di ricerca ottimizzati per le entrate.
purchase-complete in media di eventi attribuibili a un search evento per prodotto con prezzo disponibile per la ricerca 0,5 negli ultimi 30 giorni Consigliato per i risultati di ricerca ottimizzati per le entrate.

Requisiti per la personalizzazione della Ricerca

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 pubblicati dalla ricerca 100.000 negli ultimi 30 giorni

Almeno 100.000 eventi pubblicati dalla ricerca negli ultimi 30 giorni sono necessari per consentire la personalizzazione.

I risultati di ricerca non vengono memorizzati nella cache Meno dell'1% dei 100.000 eventi utente più recenti

Non memorizzare nella cache i risultati di ricerca per la ricerca di testo o per le ricerche di navigazione se prevedi di utilizzare la personalizzazione. Riutilizzo degli stessi risultati tra i visitatori impedisce alla ricerca di fornire personalizzati per un determinato utente e rischia di esporre l'utente e i dati privati. La ricerca si disattiva automaticamente personalizzazione se viene rilevata la memorizzazione nella cache.

Se memorizzi nella cache solo i risultati di ricerca, la ricerca può comunque personalizzare i risultati della consultazione. Al contrario, se memorizza nella cache solo la navigazione risultati, la ricerca può comunque personalizzare la ricerca delle query di testo che consentono di analizzare i dati e visualizzare i risultati.

Corrispondenze degli ID visitatore tra SearchRequests ed eventi utente Corrispondenza di oltre il 10% per i 100.000 eventi utente più recenti Assicurati che la spaziatura e la formattazione degli ID visitatore corrispondano tra SearchRequests e gli eventi utente. ID visitatore coerente la formattazione assicura che la ricerca possa identificare attività utente in modo corretto.

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 Pixel e Tag Manager JavaScript. Per BigQuery, viene fornito lo schema completo della tabella per ogni tipo.

Per tutti i tipi di eventi utente, il campo userId è facoltativo. Le informazioni sul prodotto (priceInfo e availability) sono facoltativo.

Ricorda:

  • Il campo experimentIds è necessario solo se stai eseguendo un esperimento A/B.
  • Il campo attributionToken è obbligatorio solo per Vertex AI Search per il retail. È utilizzato per per misurare il rendimento. predict, search e detail-page-view gli eventi generati dai clic devono avere il token di attribuzione al fine di ricollegare gli eventi alle ricerche i suggerimenti che li hanno generati.
  • Assicurati che tutti gli eventi utilizzino un'unica valuta, soprattutto se prevedi di utilizzare console Google Cloud per ottenere le metriche relative alle entrate. L'API Vertex AI Search for Retail non supporta l'utilizzo più valute per catalogo.

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

Aggiungi al carrello

Di seguito viene mostrato il formato degli eventi utente add-to-cart.

Oggetto Aggiungi al carrello minimo richiesto

I seguenti esempi mostrano solo i campi obbligatori dell'utente add-to-cart formato dell'evento.

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

Potrebbero essere richiesti altri campi a seconda del metodo API utilizzato o se vengono utilizzati altri campi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per informazioni dettagliate su ogni campo e quando sono richiesti, 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. Modalità per i campi facoltativi sono impostati su NULLABLE.

Tieni presente che eventTime è obbligatorio per l'importazione degli 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 degli eventi utente category-page-view.

Oggetto di visualizzazione di pagina della categoria richiesto minimo

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

Sebbene in genere a una pagina sia 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 richiesti 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 informazioni dettagliate su ogni campo e su quando sono richiesti, 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 è obbligatorio per l'importazione degli eventi con BigQuery. eventTime è una stringa con 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.

Numero minimo di oggetti obbligatori per le visualizzazioni di pagina dei dettagli

Gli esempi seguenti mostrano solo i campi obbligatori dell'attributo detail-page-view formato degli eventi utente.

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

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

Potrebbero essere richiesti 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 informazioni dettagliate su ogni campo e quando sono richiesti, 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 è obbligatorio per importare eventi con in 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 degli eventi utente home-page-view.

Numero minimo di oggetti richiesti per home-page-view

Gli esempi seguenti mostrano solo i campi obbligatori dell'attributo home-page-view formato degli eventi utente.

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

Potrebbero essere richiesti 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 informazioni dettagliate su ogni campo e quando sono richiesti, 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. Modalità per i campi facoltativi sono impostati su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare eventi con in 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 viene mostrato il formato dei dati sugli eventi utente purchase-complete.

Oggetto purchase-complete minimo richiesto

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

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

Potrebbero essere richiesti altri campi a seconda del metodo API utilizzato o se vengono utilizzati altri campi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per informazioni dettagliate su ogni campo e quando sono richiesti, 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 è obbligatorio per importare eventi con in BigQuery. eventTime è una stringa con 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 degli eventi utente search.

Oggetto di ricerca minimo richiesto

Gli esempi riportati di seguito mostrano solo i campi obbligatori del formato dell'evento utente search.

È obbligatorio specificare almeno un valore per il campo searchQuery o pageCategories.

productDetails deve includere l'elenco degli ID prodotto mostrati all'utente finale nella pagina dei risultati di ricerca.

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

Potrebbero essere richiesti 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 informazioni dettagliate su ogni campo e quando sono richiesti, 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 è obbligatorio per importare eventi con in BigQuery. eventTime è una stringa con 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 riportati di seguito mostrano il campo completionDetail quando un utente digita "sh" 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 completionDetail campo 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 è obbligatorio per l'importazione degli eventi con BigQuery. eventTime è una stringa con 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.

Oggetto minimo richiesto per visualizzazione pagina del carrello degli acquisti

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

Fornisci l'oggetto productDetails, a meno che il carrello degli acquisti non sia vuoto.

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

Potrebbero essere richiesti altri campi a seconda del metodo API utilizzato o se vengono utilizzati altri campi. Ad esempio, se l'evento utente è associato a un'entità, assicurati di specificare il campo entity. Per informazioni dettagliate su ogni campo e su quando sono richiesti, 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"
     },
     {
       "id": "product-id"
     }
   }]
};

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'
           },
           {
             '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. Modalità per i campi facoltativi sono impostati su NULLABLE.

Tieni presente che eventTime è obbligatorio per l'importazione degli 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 seguente tabella mostra come vengono mappati i campi degli eventi utente di Google Analytics 4 ai campi di Vertex AI Search for Retail.

Prima di importare o registrare gli eventi utente da Google Analytics 4, assicurati di: che gli eventi utente di Google Analytics 4 utilizzino i seguenti campi in modo che che Vertex AI Search for Retail possa integrare correttamente i 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

Attributi personalizzati

Puoi includere altri attributi e funzionalità personalizzati per gli eventi utente. Ciò può portare a consigli migliori e più specifici per i tuoi utenti quando li utilizzi. Per aggiungere attributi personalizzati, utilizza attributes quando registri un evento utente.

Se fornisci attributi personalizzati per gli eventi utente importati, è importante che includerle anche negli eventi utente che associ alla previsione richieste. La formattazione degli attributi personalizzati deve essere coerente tra gli eventi importati e quelli forniti con richieste di previsione. Ciò consente di questi attributi personalizzati durante l'addestramento dei modelli la pubblicazione delle previsioni, il che contribuisce a migliorare la qualità dei suggerimenti.

Puoi fornire valori di testo personalizzati utilizzando il campo text oppure utilizzando il campo number.

Ad esempio, di seguito è riportata la sezione attributes di una richiesta per registrare un evento utente:

"attributes": {
  "user_age": {"text": ["teen", "young adult"]},
  "user_location": {"text": ["CA"]}
}

Informazioni sull'utente

visitorId rappresenta l'identificatore dell'utente unico ed è obbligatorio quando registrare un evento utente.

Le informazioni sull'utente (UserInfo) incluse quando registri un evento dell'utente contengono il valore visitorId e, se disponibile, il valore userId. userId è facoltativo e può essere utilizzato come Un identificatore univoco permanente per un utente su più dispositivi ogni volta che un utente registra nel tuo sito. Quando registri il userId per un utente, Vertex AI Search per il retail può generare risultati più personalizzati per un utente su più dispositivi, ad esempio un dispositivo mobile e un browser web.

Informazioni sul timestamp

Quando registri un evento utente, assicurati di includere un timestamp accurato che indichi quando in cui si è verificato l'evento. Timestamp precisi assicurano che gli eventi siano archiviati nel nell'ordine corretto. I timestamp vengono registrati automaticamente per gli eventi raccolti utilizzando Tag Manager e il pixel JavaScript. Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Passaggi successivi