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 |
|
Importante per migliorare la qualità del modello di suggerimenti nel tempo |
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:
- Requisiti dell'API Retail: requisiti generali degli eventi utente per l'API Retail. Questi requisiti si applicano a prescindere dall'utilizzo di Recommendations e Retail Search.
- Requisiti specifici per i suggerimenti: requisiti degli eventi utente per i suggerimenti.
- Requisiti specifici per Retail Search: requisiti per gli eventi utente per Retail Search.
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, |
|
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 |
Gli eventi |
Includi esattamente un 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 |
|
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, |
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 |
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 eventipredict
,search
edetail-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" } ]
Ricerca
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
- Scopri come registrare gli eventi utente.