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 |
|
Importante per migliorare la qualità del modello Recommendations AI nel tempo |
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:
- Requisiti dell'API Retail: requisiti generali per gli eventi utente per l'API Retail. Questi requisiti si applicano indipendentemente dal fatto che utilizzi Recommendations AI e Retail Search.
- Requisiti specifici di Recommendations AI: requisiti per gli eventi utente per Recommendations AI.
- Requisiti specifici per la Ricerca al dettaglio: requisiti per gli eventi utente per la Ricerca al dettaglio.
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, |
|
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 |
Gli eventi |
Includi un solo 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 |
|
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 |
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 |
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 eventipredict
,search
edetail-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" } ]
Cerca
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
- Scopri come registrare gli eventi utente.