Informazioni sugli eventi utente

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

Retail usa gli eventi utente in tempo reale per generare consigli e risultati di ricerca. Quando carichi i dati nell'API Retail, sia Recommendationss che Retail Search potranno utilizzare questi dati, quindi non è necessario caricare gli stessi eventi due volte se usi entrambi i servizi.

Per assistenza con la registrazione degli eventi utente, consulta Registrare 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.
categoria-visualizzazione-di-pagina Visualizza le pagine speciali, ad esempio quelle dei saldi o delle promozioni.
visualizzazione-di-pagina-dettaglio Visualizza la pagina dei dettagli del prodotto.
visualizzazione-home-page 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à tipo di evento

Per ottenere risultati di qualità ottimale, ti consigliamo di registrare gli eventi utente per tutti i tipi di eventi. La tabella seguente descrive la priorità dei diversi tipi di eventi utente. Devi registrare gli eventi utente con la massima priorità per ottenere modelli dei 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 Retail Search)

Importante per migliorare la qualità del modello di 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 da Recommendations e Retail Search. Controlla che i tuoi eventi utente soddisfino questi requisiti in modo che l'API Retail possa generare risultati di qualità.

In questa sezione sono elencati:

Se utilizzi i modelli di suggerimenti, consulta anche Requisiti dei dati dei tipi di modelli, che elenca ulteriori requisiti in base al tipo di modello di suggerimento e all'obiettivo di ottimizzazione che prevedi di utilizzare.

Puoi visualizzare le metriche sulla qualità dei dati per Retail Search nella pagina Qualità dei dati della console Retail. 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, consulta Sbloccare i livelli di prestazioni della ricerca.

Requisiti dell'API Retail

Assicurati che i tuoi eventi utente soddisfino i seguenti requisiti in modo che l'API Retail possa generare risultati di qualità. Queste norme si applicano sia ai Consigli che a Retail Search.

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 prevengono il successo dell'addestramento del modello. Gli eventi duplicati possono causare valori delle metriche errati.

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

Ciò garantisce che l'API Retail abbia dati sufficienti per generare risultati di qualità.

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

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

I prodotti inclusi negli eventi devono essere presenti nel tuo catalogo dei prodotti.

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

I dati sugli eventi non uniti non vengono utilizzati per addestrare i modelli. Tuttavia, gli eventi non uniti possono essere uniti in un secondo momento, dopo che i prodotti associati sono stati importati. Per maggiori informazioni, consulta Riunire gli eventi utente.

Alcuni eventi utente devono avere lo stesso ID visitatore.

Per creare cronologie di sequenze di comportamenti valide, Retail deve essere in grado di visualizzare più eventi con lo stesso ID visitatore.

Ad esempio, visitor123 ha visualizzato cinque pagine dei dettagli dei prodotti, 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 formattazione coerente, Retail può prendere in considerazione questa sequenza di comportamento nei propri modelli.

detail-page-view

Includi esattamente un prodotto per evento.

Impossibile utilizzare l'evento se non esiste nessun prodotto. Se vengono inclusi più prodotti, l'evento non è nel formato corretto e non può essere utilizzato.

add-to-cart

Includi esattamente un prodotto per evento.

Se vengono inclusi più prodotti, l'evento non è nel formato corretto e non può essere utilizzato.

purchase-complete

Includi purchase_transaction.revenue.

Gli eventi purchase-complete in 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; è necessario specificare un codice.

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

Verifica che alcuni eventi di acquisto includano più prodotti.

Avere alcuni eventi di acquisto con più prodotti aiuta il modello ad apprendere i pattern di acquisto collaborativo.

Requisiti specifici dei consigli

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

Se utilizzi i modelli di suggerimenti, consulta anche Requisiti dei dati dei tipi di modelli, che elenca ulteriori requisiti in base al tipo di modello di suggerimento e all'obiettivo di ottimizzazione che prevedi di utilizzare.

Tipo di evento Requisito Impatto
purchase-complete

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

In questo modo ti assicuri che vengano generati pattern di co-acquisto validi.

Requisiti di Retail Search

Se utilizzi Retail Search, assicurati che i tuoi 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 per gli eventi di navigazione.

Il mancato inserimento 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, gli eventi non sono corretti e le metriche potrebbero essere errate.

L'elenco degli ID prodotto negli eventi di ricerca deve corrispondere all'intero elenco di prodotti mostrato all'utente.

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

Se questo campo non esiste, l'API Retail non può utilizzare la parte dei dati del filtro, il che può influire negativamente sulla qualità dei risultati di ricerca.

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

L'esclusione di un token di ricerca ha un grave impatto negativo sulla qualità della ricerca e sull'accuratezza delle metriche.

Requisiti per l'ottimizzazione della ricerca

Per consentire a Retail Search 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 massimo di 24 ore.

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

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

Consigliamo di caricare gli eventi almeno una volta al giorno per mantenere una buona qualità dei dati. Durante le importazioni degli eventi storici, assicurati che la distribuzione dei dati sia in linea con il timestamp più recente. Il numero di eventi nell'ultimo giorno del timestamp deve essere uguale o superiore al conteggio medio degli eventi giornaliero.

Volume di detail-page-view attribuibile a un evento search 500.000 negli ultimi 30 giorni Per ottimizzare i risultati di ricerca utilizzando gli eventi utente,sono obbligatori almeno 500.000.
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 importati, a meno che non vengano caricati eventi degli ultimi 21 giorni.
Proporzione di eventi search con filtri analizzabili 0,1 negli ultimi 30 giorni Opzione consigliata 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 importati.
Media eventi add-to-cart attribuibili a un evento search per prodotto con prezzo 0,5 negli ultimi 30 giorni Consigliato per i risultati di ricerca ottimizzati per le entrate.
Media di eventi purchase-complete attribuibili a un evento search 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 di personalizzazione della Ricerca

Retail Search richiede i seguenti dati per personalizzare la ricerca testuale e sfogliare i risultati di ricerca per i tuoi utenti in base alla loro attività.

Dopo che avrai caricato i seguenti dati, Retail Search potrà personalizzare i risultati automaticamente.

Metrica Eventi Volume/frequenza eventi Descrizione
Volume di search eventi gestiti da Retail Search 100.000 negli ultimi 30 giorni

Per fornire la personalizzazione,sono necessari almeno 100.000 eventi gestiti da Retail Search negli ultimi 30 giorni.

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

Non memorizzare nella cache i risultati di Retail Search per la ricerca testuale o per le ricerche di navigazione se prevedi di utilizzare la personalizzazione. Il riutilizzo degli stessi risultati tra i visitatori impedisce a Retail Search di fornire risultati veramente personalizzati a un determinato utente e rischia di esporre i dati privati degli utenti. Retail Search disattiva automaticamente la personalizzazione se viene rilevata la memorizzazione nella cache.

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

L'ID visitatore corrisponde tra SearchRequests e gli eventi utente Una corrispondenza superiore al 10% per gli ultimi 100.000 eventi utente Assicurati che la spaziatura e la formattazione dell'ID visitatore corrispondano tra SearchRequests e gli eventi utente. La formattazione coerente degli ID visitatore garantisce che Retail Search possa identificare correttamente l'attività utente.

Esempi e schemi di tipi di eventi utente

Questa sezione fornisce i formati dei dati per ogni tipo di evento supportato dall'API Retail.

Vengono forniti esempi di 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 esegui un esperimento A/B.
  • Il campo attributionToken è facoltativo; viene utilizzato per misurare il rendimento. Gli eventi predict, search e detail-page-view generati dai clic dell'API Retail devono avere un token di attribuzione per ricollegare gli eventi alle ricerche o ai suggerimenti che li hanno generati.
  • Assicurati che tutti i tuoi eventi utilizzino un'unica valuta, soprattutto se prevedi di utilizzare Google Cloud Console per visualizzare le metriche sulle entrate. L'API Retail non supporta l'uso di più valute per catalogo.

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

Numero minimo di oggetto Aggiungi al carrello richiesto

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

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 dell'utilizzo di 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 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": 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 durante la creazione delle 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 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 oggetto categoria-visualizzazione di pagina

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

Di solito a ogni pagina è associata una sola categoria, ma il campo pageCategories supporta anche una gerarchia di categorie, che puoi fornire sotto forma di 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 dell'utilizzo di 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 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 durante la creazione delle 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 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 viene mostrato il formato dei dati sugli eventi utente detail-page-view.

Oggetto dettaglio-visualizzazione-pagina-minimo obbligatorio

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

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 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 dell'utilizzo di 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 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 durante la creazione delle 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 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": "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 oggetto con visualizzazione della home page richiesto

Gli esempi seguenti mostrano solo i campi obbligatori del formato di 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 dell'utilizzo di 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 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 durante la creazione delle 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 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 viene mostrato il formato dei dati sugli eventi utente purchase-complete.

Oggetto acquisto-completato minimo obbligatorio

Gli esempi seguenti mostrano solo i campi obbligatori del formato di 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 dell'utilizzo di 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 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 durante la creazione delle 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 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.

Numero minimo di oggetto di ricerca richiesto

Gli esempi seguenti mostrano solo i campi obbligatori del formato degli eventi 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 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 dell'utilizzo di 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 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 durante la creazione delle 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 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 solo per gli eventi di ricerca se vuoi utilizzare il completamento automatico. Non è obbligatorio per la ricerca.

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

eventType deve essere "search".

completionAttributionToken è la risposta attributionToken da 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 durante la creazione delle 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 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 viene mostrato il formato dei dati sugli eventi utente shopping-cart-page-view.

Numero minimo di oggetto Shopping-cart-page-view obbligatorio

I seguenti esempi mostrano solo i campi obbligatori del formato di 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 necessari altri campi, a seconda del metodo API utilizzato o dell'utilizzo di 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 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"
     },
     {
       "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 durante la creazione delle 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 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"
 }
]

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 Vendita al dettaglio.

Prima di importare o registrare eventi utente da Google Analytics 4, assicurati che questi ultimi utilizzino i seguenti campi in modo che Retail possa integrare correttamente i tuoi dati.

Google Analytics 4 Retail
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 personalizzati e funzionalità per gli eventi utente. Ciò può portare a suggerimenti migliori e più specifici per gli utenti quando utilizzi i consigli. Per aggiungere attributi personalizzati, utilizza attributes quando registri un evento utente.

Se fornisci attributi personalizzati per gli eventi utente importati, è importante includerli anche negli eventi utente associati alle richieste di previsione. La formattazione degli attributi personalizzati deve essere coerente tra gli eventi importati e quelli forniti con le richieste di previsione. In questo modo l'API Retail può utilizzare questi attributi personalizzati durante l'addestramento di modelli e la pubblicazione delle previsioni, il che contribuisce a migliorare la qualità dei suggerimenti.

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

Ad esempio, quanto segue mostra la sezione attributes di una richiesta di registrazione di un evento utente:

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

Informazioni sull'utente

visitorId rappresenta l'identificatore utente univoco ed è obbligatorio quando registri un evento utente.

Le informazioni sull'utente (UserInfo) incluse quando registri un evento utente contengono il valore visitorId e, se disponibile, il valore userId. userId è facoltativo e può essere utilizzato come identificatore univoco e permanente per un utente su più dispositivi ogni volta che un utente accede al tuo sito. Quando registri userId per un utente, l'API Retail può generare risultati più personalizzati per l'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 si è verificato l'evento. Timestamp precisi assicurano che l'API Retail memorizzi gli eventi nell'ordine corretto. I timestamp vengono registrati automaticamente per gli eventi raccolti utilizzando Tag Manager e il pixel JavaScript. Quando importi eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Passaggi successivi