Informazioni sugli eventi utente

In questa pagina viene descritto l'oggetto evento utente, incluso l'elenco dei potenziali tipi di eventi utente, e vengono forniti dati di esempio per tutti i tipi di eventi utente.

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

Per assistenza sulla registrazione di eventi utente, consulta Registrare eventi utente in tempo reale.

Tipi di eventi utente

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

Nome evento utente Azione utente
aggiungi al carrello Aggiunge un prodotto al carrello.
visualizzazione-pagina-categoria Visualizza le pagine speciali, come quelle per sconti o promozioni.
visualizzazione-pagina-dettagliata Visualizza la pagina dei dettagli del prodotto.
visualizzazione-home-home Visualizza la home page.
purchase-complete Completa il pagamento.
ricerca Cerca nel catalogo.
shopping-page-cart-shopping Visualizza il carrello degli acquisti.

Per informazioni dettagliate sull'oggetto UserEvent, consulta UserEvent.

Priorità dei tipi di eventi

Per ottenere i migliori risultati possibili, ti consigliamo di registrare gli eventi utente per tutti i tipi di eventi. La seguente tabella descrive la priorità dei diversi tipi di eventi utente. Devi registrare gli eventi utente con la massima priorità per ottenere modelli di dati di qualità.

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

add-to-cart

detail-page-view

purchase-complete

home-page-view (per Recommendations AI)

search (per Retail Search)
Importante per migliorare la qualità del modello Recommendations AI nel tempo

category-page-view

search

shopping-cart-page-view

Best practice e requisiti per gli eventi utente

Le seguenti tabelle elencano i requisiti e le best practice per i tipi di eventi utente utilizzati da Recommendations AI e Retail Search. Verifica che gli 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 Recommendations AI, consulta anche la sezione Requisiti dei dati del tipo di modello, che elenca i requisiti aggiuntivi a seconda del tipo di modello di suggerimenti e dell'obiettivo di ottimizzazione che prevedi di utilizzare.

Puoi visualizzare le metriche sulla qualità dei dati anche nel riquadro Qualità dei dati nella pagina Dati della console Retail. Queste metriche mostrano le percentuali di prodotti ed eventi utente che soddisfano gli standard consigliati della qualità dei dati. Per maggiori dettagli su come visualizzare la qualità dei dati, consulta Metriche sulla qualità dei dati.

Requisiti dell'API Retail

Assicurati che gli eventi utente soddisfino i seguenti requisiti in modo che l'API Retail possa generare risultati di qualità. Si applicano sia a Recommendations AI che a Retail Search.

Tipo di evento Requisito Impatto
Tutti gli eventi

Non includere dati sintetici o eventi duplicati.

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

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

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

Gli ID visitatore devono essere formattati esattamente per l'importazione evento o la registrazione di 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 fornire risultati di qualità migliore in base al comportamento dell'utente.

I prodotti inclusi negli eventi devono essere presenti nel tuo catalogo di 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 associati non vengono utilizzati per addestrare i modelli. Tuttavia, gli eventi non uniti possono essere uniti in un secondo momento, dopo l'importazione dei prodotti associati. Per ulteriori informazioni, vedi Riassociare gli eventi utente.

Alcuni eventi utente devono avere lo stesso ID visitatore.

Per creare cronologie di sequenza del comportamento valide, Retail deve essere in grado di vedere più eventi con lo stesso ID visitatore.

Ad esempio, visitor123 ha visualizzato cinque pagine dei dettagli dei prodotti, ne ha aggiunti tre al carrello e ha acquistato due dei cinque prodotti originali. Se tutti questi eventi forniscono lo stesso ID visitatore con formattazione coerente, la vendita al dettaglio può prendere in considerazione la sequenza di comportamenti nei propri 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, il formato dell'evento non è valido e non può essere utilizzato.

add-to-cart

Includi esattamente un prodotto per evento.

Se sono inclusi più prodotti, il formato dell'evento non è valido 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 l'addestramento dei modelli.

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

Non esiste un codice valuta predefinito, ma è necessario specificarne uno.

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

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

Requisiti specifici per l'Recommendations AI

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

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

Tipo di evento Requisito Impatto
purchase-complete

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

Questo garantisce 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 deve esistere per gli eventi di navigazione.

L'esclusione 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 relativi 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'elenco completo dei prodotti mostrati all'utente.

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

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

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

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

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

Requisiti di ottimizzazione della ricerca

Per consentire a Retail Search di ottimizzare automaticamente l'esperienza di ricerca in base alle tendenze complessive degli utenti, carica i seguenti dati.

Gli eventi devono essere caricati almeno ogni giorno con un ritardo massimo di 24 ore.

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

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

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

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 eventi.
Media 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 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 di ricerca.
Quota 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 eventi in media attribuibili a un evento search per prodotto a prezzo 0,5 negli ultimi 30 giorni Consigliato per i risultati di ricerca ottimizzati per le entrate.
Valore medio di eventi purchase-complete attribuibili a un evento search per prodotto a 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

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 aver caricato i seguenti dati, Retail Search può personalizzare automaticamente i risultati.

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

Per fornire la personalizzazione sono necessari almeno 100.000 eventi pubblicati 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 di testo e non sfogliare le ricerche se prevedi di utilizzare la personalizzazione. Il riutilizzo degli stessi risultati tra i visitatori impedisce a Retail Search di fornire risultati realmente 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 memorizzare 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 ricerca, Retail Search può comunque personalizzare i risultati di ricerca delle query di testo.

Corrispondenze ID visitatore tra SearchRequests ed eventi utente Una corrispondenza superiore al 10% per i 100.000 eventi utente più recenti Assicurati che la spaziatura e la formattazione degli ID visitatore corrispondano a SearchRequests ed eventi utente. La formattazione coerente degli ID visitatore garantisce che Retail Search possa identificare correttamente l'attività utente.

Esempi di schemi di eventi utente e schemi

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

Sono forniti esempi per Pixel JavaScript e Tag Manager. Per BigQuery, viene fornito lo schema di tabella completo per ogni tipo.

La colonna userId è facoltativa per tutti i tipi di eventi utente. I campi delle informazioni sul prodotto (priceInfo e availability) sono facoltativi.

Ricorda:

  • Il campo experimentIds è obbligatorio solo se stai eseguendo 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 sull'API Retail devono avere un token di attribuzione per collegare gli eventi alle ricerche o ai suggerimenti che li hanno generati.
  • Assicurati che tutti gli eventi utilizzino una sola valuta, soprattutto se prevedi di utilizzare Google Cloud Console per ottenere le metriche delle entrate. L'API Retail non supporta l'utilizzo di più valute per catalogo.

Per maggiori dettagli sull'oggetto evento utente, consulta la documentazione di riferimento per l'API UserEvent.

Aggiungi al carrello

Di seguito è mostrato il formato di evento utente add-to-cart.

Oggetto minimo da aggiungere al carrello

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

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

Altri campi potrebbero essere obbligatori a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Per i dettagli completi di ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": 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 le 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 di 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"
 }
]

Visualizzazione pagina delle categorie

Di seguito è mostrato il formato di evento utente category-page-view.

Oggetto minimo obbligatorio per la visualizzazione di pagina

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

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

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

Altri campi potrebbero essere obbligatori a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Per i dettagli completi di ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

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

Tag Manager 

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

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei le 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 di 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"
 }
]

Visualizzazione pagina dei dettagli

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

Oggetto minimo della visualizzazione dettagliata della pagina

Gli esempi seguenti mostrano solo i campi obbligatori del formato 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 eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Altri campi potrebbero essere obbligatori a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Per i dettagli completi di ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

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

Tag Manager 

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

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei le 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 di 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"
 }
]

Visualizzazione home page

Di seguito è mostrato il formato di evento utente home-page-view.

L'oggetto visualizzazione della home page è minimo richiesto

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

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

Altri campi potrebbero essere obbligatori a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Per i dettagli completi di ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

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

Tag Manager 

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

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei le 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 di 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"
 }
]

Acquisto completato

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

Oggetto minimo richiesto per il completamento dell'acquisto

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

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

Altri campi potrebbero essere obbligatori a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Per i dettagli completi di ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

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

Tag Manager 

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

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei le 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 di 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"
 }
]

Di seguito è mostrato il formato di evento utente search.

Oggetto di ricerca minimo richiesto

I seguenti esempi mostrano solo i campi obbligatori del formato evento utente search.

È necessario specificare almeno un campo searchQuery o pageCategories.

productDetails deve includere l'elenco di ID prodotto mostrato 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.

Altri campi potrebbero essere obbligatori a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Per i dettagli completi di ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

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

Tag Manager 

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

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei le 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 di 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"
 }
]

Completamento automatico

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

I seguenti esempi 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, il campo completionDetail rimane vuoto.

eventType deve essere "search".

completionAttributionToken è il attributionToken di 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 le 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 di 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 è mostrato il formato dei dati sugli eventi utente di shopping-cart-page-view.

Oggetto minimo obbligatorio per la visualizzazione della pagina del carrello degli acquisti

I seguenti esempi mostrano solo i campi obbligatori del formato 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.

Altri campi potrebbero essere obbligatori a seconda del metodo API utilizzato o se vengono utilizzati campi aggiuntivi. Per i dettagli completi di ogni campo e quando sono obbligatori, consulta la documentazione di riferimento dell'API UserEvent.

Pixel JavaScript

var user_event = {
  "eventType": "shopping-cart-page-view",
  "visitorId": "visitor-id
  "cartId": "cart-id",
  "productDetails": [{
    "product": {
       "id": "product-id"
     },
     {
       "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 le 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 di 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"
 }
]

Attributi personalizzati

Puoi includere attributi e funzionalità personalizzati aggiuntivi per gli eventi utente. Questo può comportare suggerimenti migliori e più specifici per i tuoi utenti quando utilizzi Recommendations AI. Per aggiungere attributi personalizzati, utilizza attributes quando registri un evento utente.

Se specifichi 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 gli eventi forniti con le richieste di previsione. In questo modo l'API Retail può utilizzare questi attributi personalizzati durante l'addestramento di modelli e fornire previsioni, contribuendo a migliorare la qualità dei suggerimenti.

Puoi fornire valori di testo personalizzati utilizzando il campo text oppure 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 sugli utenti

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

Le informazioni 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 tutti i dispositivi ogni volta che l'utente accede al sito. Quando registri userId per un utente, l'API Retail può generare risultati più personalizzati per un utente su più dispositivi, ad esempio sia un dispositivo mobile sia un browser web.

Informazioni sul timestamp

Quando registri un evento utente, assicurati di includere un timestamp preciso di quando si è verificato. Timestamp accurati garantisce che l'API Retail archivi gli eventi nell'ordine corretto. I timestamp vengono registrati automaticamente per gli eventi raccolti tramite Tag Manager e Pixel di JavaScript. Quando importi eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Passaggi successivi