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 per il retail utilizza gli eventi utente in tempo reale per generare consigli e risultati di ricerca. Quando carichi i dati, i suggerimenti e la ricerca possono utilizzare quindi non è necessario caricare gli stessi eventi due volte se li utilizzi i servizi di machine learning.

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
aggiungi al carrello 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.
acquisto-completato 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 massima qualità, ti consigliamo di registrare gli eventi utente per tutti i tipi di eventi. La tabella seguente descrive la priorità delle diverse tipi di eventi utente. Per ottenere modelli di dati di qualità, devi registrare gli eventi utente con la priorità più elevata.

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 utilizzati dai consigli e dalla ricerca. Verifica che gli eventi utente soddisfano questi requisiti affinché Vertex AI Search for Retail possono generare risultati di qualità.

In questa sezione sono elencati:

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 le percentuali di prodotti ed eventi utente che soddisfano gli standard consigliati per la qualità dei dati. Per informazioni su come visualizzare la qualità dei dati di ricerca, consulta Sblocca i livelli di rendimento della ricerca.

Requisiti per gli eventi utente

Assicurati che gli eventi utente soddisfino i seguenti requisiti affinché Vertex AI Search per la vendita al dettaglio possa 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 errati delle metriche.

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

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 maggiori informazioni, vedi Riunire gli eventi utente.

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 questi eventi forniscono lo stesso con formattazione coerente, Vertex AI Search for Retail può considerare quella 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 sono inclusi più prodotti, l'evento non è formattato correttamente e non può essere utilizzato.

add-to-cart

Includi esattamente un prodotto per evento.

Se sono inclusi più prodotti, l'evento ha un formato non valido e non può essere in uso.

purchase-complete

Includi purchase_transaction.revenue.

purchase-complete eventi a cui manca il simbolo I campi revenue non vengono utilizzati per addestrare i modelli.

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

Non esiste un codice valuta predefinito. è necessario specificare un codice.

Gli eventi di acquisto senza questo campo generano metriche sulle entrate sbagliate.

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 per i 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 suddividere i cestini di più articoli in più eventi di acquisto. Deve rimanere come singolo evento di acquisto che include più prodotti.

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

Requisiti 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 Per gli eventi di navigazione è necessario specificare pageCategories.

L'esclusione di questo campo può avere un grave impatto negativo sulla ricerca la qualità dei risultati e le metriche.

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

Se non corrispondono, gli eventi non sono formattati correttamente e le metriche potrebbero essere scorrette.

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 grave e le metriche saranno errate.

Se la ricerca utilizza un filtro, filter deve esistere e analizzare in modo corretto.

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

Includi il campo attribution_token per collegare altri eventi 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 rete di 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 nell'ultimo giorno del timestamp deve essere uguale o superiore al conteggio giornaliero medio degli eventi.

Volume di detail-page-view attribuibile a un search evento 500.000 negli ultimi 30 giorni Per ottimizzare i risultati di ricerca utilizzando gli eventi utente, sono necessari almeno 500.000 eventi.
Eventi detail-page-view medi 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 l'ottimizzazione dei risultati di ricerca utilizzando gli eventi acquisiti.
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.
Eventi purchase-complete medi attribuibili a un search evento per prodotto con prezzo visualizzabile 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 testuale e sfogliare i risultati di ricerca visualizzati dai tuoi 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 search eventi pubblicati dalla ricerca 100.000 negli ultimi 30 giorni

Per fornire la personalizzazione sono necessari almeno 100.000 eventi pubblicati 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 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 disattiva automaticamente la personalizzazione se viene rilevata la memorizzazione nella cache.

Se memorizzi nella cache solo i risultati di ricerca, la ricerca può personalizzare i risultati di 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 degli ID visitatore tra SearchRequests e gli eventi utente Più del 10% di corrispondenza per gli ultimi 100.000 eventi utente Assicurati che la spaziatura e la formattazione degli ID visitatore corrispondano tra loro SearchRequests ed 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, 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 per il retail. Viene utilizzata per misurare il rendimento. Gli eventi predict, search e detail-page-view generati dai clic devono avere un token di attribuzione per collegare gli eventi alle ricerche o ai consigli 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

Gli esempi riportati di seguito mostrano solo i campi obbligatori del formato dell'evento add-to-cart per gli utenti.

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": "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 per importare gli eventi coneventTime 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": "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.

Numero minimo obbligatorio di oggetti categoria-visualizzazione di pagina

Gli esempi seguenti mostrano solo i campi obbligatori dell'attributo category-page-view formato degli eventi 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 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": "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 per importare gli eventi coneventTime 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": "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 un set di articoli non venga venduto insieme.

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": "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 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": "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 riportati di seguito mostrano solo i campi obbligatori del formato dell'evento home-page-view utente.

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": "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 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": "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.

Oggetto acquisto-completato 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 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": "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. Modalità per i campi facoltativi sono impostati su NULLABLE.

Tieni presente che per importare gli eventi coneventTime 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": "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 è riportato il formato dell'evento utente search.

Numero minimo di oggetti di ricerca richiesto

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

È obbligatorio specificare almeno un 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 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": "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. 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": "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 solo per gli eventi di ricerca se vuoi utilizzare 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 alcun suggerimento, l'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 è 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": "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 shopping-cart-page-view minimo richiesto

I seguenti esempi 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 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 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 per importare gli eventi coneventTime 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": "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 degli eventi 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 che gli eventi utente di Google Analytics 4 utilizzino i seguenti campi in modo che Vertex AI Search for Retail 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

Attributi personalizzati

Puoi includere ulteriori attributi e funzionalità personalizzati per gli eventi utente. Questo può portare a consigli migliorati e più specifici per gli utenti quando utilizzare i consigli. 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 le richieste di previsione. In questo modo, è possibile utilizzare questi attributi personalizzati durante l'addestramento dei modelli e la pubblicazione delle previsioni, il che contribuisce a migliorare la qualità dei consigli.

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

Ad esempio, quanto segue mostra 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 univoco utente ed è obbligatorio quando registri 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 preciso del momento in cui si è verificato. 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