Questa è la documentazione di Recommendations AI, Retail Search e la nuova console di Retail.

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.

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

Per informazioni sulla registrazione di eventi utente, vedi 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 utente
aggiungi al carrello Aggiunge il prodotto al carrello.
visualizzazione-pagina-categoria Visualizza le pagine speciali, come quelle per saldi o promozioni.
visualizzazione-pagina-dettagliata Visualizza la pagina dei dettagli del prodotto.
visualizzazione-home-page Visualizza la home page.
acquisto completato Completa il pagamento.
ricerca Cerca nel catalogo.
visualizzazione-pagina-carrello Visualizza il carrello degli acquisti.

Per informazioni dettagliate sull'oggetto UserEvent, consulta UserEvent.

Priorità del tipo di evento

Per ottenere risultati della massima qualità, ti consigliamo di registrare gli eventi utente per tutti i tipi di eventi. La tabella seguente descrive la priorità dei diversi tipi di evento utente. Per ottenere modelli di dati di qualità, devi registrare gli eventi utente con priorità più elevata.

Priorità Eventi utente
Obbligatorio per l'esperimento iniziale iniziale

add-to-cart

detail-page-view

purchase-complete

home-page-view (per Recommendations AI)

search (per la vendita al dettaglio)

Importante per migliorare la qualità del modello Recommendations AI nel tempo

category-page-view

search

shopping-cart-page-view

Requisiti e best practice per gli eventi degli utenti

Le seguenti tabelle elencano i requisiti e le best practice per i tipi di eventi utente utilizzati da Recommendations AI e Retail. 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 Recommendations AI, consulta anche i requisiti dei dati degli eventi utente, che elencano i requisiti aggiuntivi a seconda del tipo di modello di suggerimento e dell'obiettivo di ottimizzazione che vuoi utilizzare.

Puoi visualizzare le metriche sulla qualità dei dati anche nel riquadro Qualità dei dati nella pagina Dati della console di 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, vedi Metriche relative alla qualità dei dati.

Requisiti relativi all'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 eventi duplicati.

Gli eventi duplicati possono causare valori di metriche errati e influire negativamente sulla qualità del modello.

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

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

Il campo Product.name è obbligatorio per tutti i prodotti. Utilizza il nome completo della risorsa del prodotto, anziché l'ID prodotto, che è il componente finale del nome della risorsa.

Un evento che include un prodotto senza un campo Product.name non può essere utilizzato dall'API Retail.

I prodotti inclusi negli eventi devono esistere nel tuo catalogo di prodotti.

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

detail-page-view

Includi esattamente un prodotto per evento.

L'evento non può essere utilizzato in assenza di un prodotto. Se sono inclusi più prodotti, l'evento ha un formato non valido e non può essere utilizzato.

add-to-cart

Includi esattamente un prodotto per evento.

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

purchase-complete

Includi purchase_transaction.revenue.

Senza questo campo, i modelli di ottimizzazione delle entrate non saranno disponibili.

Includi esattamente un elemento purchase_transaction.currency_code per tutti gli eventi di acquisto.

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

Requisiti specifici dell'AI di Recommendations

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

Se utilizzi i modelli Recommendations AI, consulta anche i requisiti dei dati degli eventi utente, che elencano i requisiti aggiuntivi a seconda del tipo di modello di suggerimento e dell'obiettivo di ottimizzazione che vuoi utilizzare.

Tipo di evento Requisito Impatto
purchase-complete

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

Ciò garantisce che vengano generati pattern di co-acquisto validi.

Requisiti specifici per la ricerca nel settore della vendita al dettaglio

Se utilizzi Ricerca Google per la vendita al dettaglio, assicurati che i tuoi eventi utente soddisfino i seguenti requisiti.

Tipo di evento Requisito Impatto
search

search_query deve esistere per gli eventi di ricerca (ad eccezione degli 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 a tale richiesta di ricerca.

Se non corrispondono, gli eventi non sono corretti e le metriche potrebbero non essere corrette.

L'elenco degli ID prodotto negli eventi di ricerca deve corrispondere all'elenco dei prodotti mostrati all'utente nella sua interezza.

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, filter deve esistere e analizzare correttamente.

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 dell'obiettivo di ricerca

Conferma che puoi soddisfare i requisiti minimi per i dati per ottimizzare automaticamente l'esperienza di ricerca in base agli eventi importati. Gli eventi devono essere caricati almeno ogni giorno con un ritardo massimo di 24 ore.

Metrica Eventi Volume/frequenza degli eventi Descrizione
Volume di eventi search 2.000.0000 negli ultimi 90 giorni Ti consigliamo di importare 2.000.000 di eventi search nell'arco di 90 giorni per ottenere analisi della qualità dei dati più dettagliate. Per ottimizzare l'esperienza di ricerca in base agli eventi importati, sono obbligatori almeno 2 milioni di eventi negli ultimi 90 giorni.
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.
Percentuale di eventi search con filtri analizzabili 0,1 negli ultimi 30 giorni Consigliato per un modello di facet dinamico efficace.
Proporzione dei 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 a prezzo 0,5 negli ultimi 30 giorni Consigliato per i risultati di ricerca ottimizzati per le entrate.
Media eventi purchase-complete attribuibili a un evento search per prodotto al prezzo disponibile per la ricerca 0,5 negli ultimi 30 giorni Consigliato per i risultati di ricerca ottimizzati per le entrate.

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 per Pixel JavaScript e Tag Manager. Per BigQuery, viene fornito lo schema tabella completo per ogni tipo.

Per tutti i tipi di eventi utente, userId è facoltativo. I campi delle informazioni sul prodotto (priceInfo e availability) sono facoltativi.

Ricorda:

  • Il campo experimentIds è necessario solo se stai eseguendo un esperimento A/B.
  • Il campo attributionToken è facoltativo, viene utilizzato per misurare il rendimento. Gli eventi predict, search e detail-page-view generati dai clic dell'API Retail devono avere un token di attribuzione per collegare gli eventi alle ricerche o ai consigli che li hanno generati.
  • Assicurati che tutti gli eventi utilizzino un'unica valuta, specialmente se intendi utilizzare Google Cloud Console per ottenere metriche sulle 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 dell'API UserEvent.

Aggiungi al carrello

Il seguente è il formato dell'evento utente add-to-cart.

Oggetto minimo richiesto per l'aggiunta

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

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

A seconda del metodo API utilizzato o dell'utilizzo di campi aggiuntivi, potrebbero essere obbligatori altri campi. 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",
  "cartId": "cart-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.
        'cartId': 'cart-id',
        'productDetails': [{
          'product': {
            'id': 'product-id'
          },
          'quantity': product-quantity
        }]
      }
    });
</script>

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare gli eventi con BigQuery. eventTime è una stringa con un formato timestamp.

[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
 {
   "name": "product",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "quantity",
   "type": "INTEGER",
   "mode": "REQUIRED"
 }
]
}
]

Visualizzazione pagina delle categorie

Il seguente è il formato dell'evento utente category-page-view.

Oggetto minimo richiesto per categoria-visualizzazione-pagina

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

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

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

A seconda del metodo API utilizzato o dell'utilizzo di campi aggiuntivi, potrebbero essere obbligatori altri campi. 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 quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare gli eventi con BigQuery. eventTime è una stringa con un formato timestamp.

[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
}
]

Visualizzazione pagina dei dettagli

Il seguente mostra il formato dei dati degli eventi utente di detail-page-view.

Oggetto minimo richiesto di visualizzazione dei dettagli della pagina

I seguenti esempi mostrano solo i campi obbligatori del formato dell'evento utente detail-page-view.

Nella maggior parte dei casi, productDetails contiene i dettagli del prodotto associato, a meno che non venga venduto in gruppo.

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

A seconda del metodo API utilizzato o dell'utilizzo di campi aggiuntivi, potrebbero essere obbligatori altri campi. 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 quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare gli eventi con BigQuery. eventTime è una stringa con un formato timestamp.

[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
 {
   "name": "product",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 }
]
}
]

Visualizzazione home page

Il seguente è il formato dell'evento utente home-page-view.

Oggetto minimo richiesto per la visualizzazione della home page

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

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

A seconda del metodo API utilizzato o dell'utilizzo di campi aggiuntivi, potrebbero essere obbligatori altri campi. 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 quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare gli eventi con BigQuery. eventTime è una stringa con un formato timestamp.

[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
}
]

Acquisto completato

Il seguente mostra il formato dei dati degli eventi utente di purchase-complete.

Oggetto minimo richiesto per l'acquisto

I seguenti esempi mostrano solo i campi obbligatori del formato dell'evento utente purchase-complete.

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

A seconda del metodo API utilizzato o dell'utilizzo di campi aggiuntivi, potrebbero essere obbligatori altri campi. 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 quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare gli eventi con BigQuery. eventTime è una stringa con un formato timestamp.

[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
  {
    "name": "product",
    "type": "RECORD",
    "mode": "REQUIRED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "REQUIRED"
      }
    ]
  },
  {
    "name": "quantity",
    "type": "INTEGER",
    "mode": "REQUIRED"
  }
]
},
{
"name": "purchaseTransaction",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
 {
   "name": "revenue",
   "type": "FLOAT",
   "mode": "REQUIRED"
 },
 {
   "name": "currencyCode",
   "type": "STRING",
   "mode": "REQUIRED"
 }
]
}
]

Il seguente è il formato dell'evento utente search.

Oggetto di ricerca minimo richiesto

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

È obbligatorio specificare almeno uno dei campi 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.

A seconda del metodo API utilizzato o dell'utilizzo di campi aggiuntivi, potrebbero essere obbligatori altri campi. 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 quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare gli eventi con BigQuery. eventTime è una stringa con un formato timestamp.

[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
 {
   "name": "product",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 }
]
},
{
"name": "searchQuery",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
}
]

Completamento automatico

Questo campo è obbligatorio per gli eventi di ricerca solo se vuoi utilizzare il completamento automatico. Non è necessario 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 è la attributionToken di risposta completeQuery.

selectedSuggestion deve corrispondere a searchQuery.

Pixel JavaScript

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

Tag Manager

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

BigQuery

Questo è lo schema JSON completo per questo tipo di evento utente. Specifica questo schema quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare gli eventi con BigQuery. eventTime è una stringa con un formato timestamp.

[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
 {
   "name": "product",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 }
]
},
{
"name": "searchQuery",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
},
{
"name": "completionDetail",
"type": "RECORD"
"mode": "NULLABLE"
"fields": [
 {
   "name": "completionAttributionToken",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "selectedSuggestion",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "selectedPosition",
   "type": "INTEGER",
   "mode": "REQUIRED"
 }
]
}
]

Visualizzazione pagina del carrello degli acquisti

Il seguente mostra il formato dei dati degli eventi utente di shopping-cart-page-view.

Oggetto minimo obbligatorio per la visualizzazione del carrello degli acquisti

I seguenti esempi mostrano solo i campi obbligatori del formato dell'evento utente shopping-cart-page-view.

Fornisci l'oggetto productDetails a meno che il carrello degli acquisti non sia vuoto.

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

A seconda del metodo API utilizzato o dell'utilizzo di campi aggiuntivi, potrebbero essere obbligatori altri campi. 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 quando crei tabelle per questo tipo di evento utente in BigQuery.

Le modalità per i campi obbligatori sono impostate su REQUIRED o REPEATED. Le modalità per i campi facoltativi sono impostate su NULLABLE.

Tieni presente che eventTime è obbligatorio per importare gli eventi con BigQuery. eventTime è una stringa con un formato timestamp.

[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
}
]

Attributi personalizzati

Puoi includere attributi personalizzati e funzionalità aggiuntive per gli eventi utente. In questo modo, puoi ottenere suggerimenti migliori e più specifici per gli utenti quando utilizzi Recommendations AI. 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 gli eventi forniti con le richieste di previsione. In questo modo, l'API Retail può utilizzare tali attributi personalizzati durante l'addestramento dei modelli e la pubblicazione delle previsioni, contribuendo a migliorare la qualità dei consigli.

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 permanente per un utente su più dispositivi ogni volta che un utente accede al tuo sito. Quando registri il valore 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 per il momento in cui si è verificato. Timestamp precisi garantiscono che l'API Retail memorizzi gli eventi nell'ordine corretto. I timestamp vengono registrati automaticamente per gli eventi raccolti utilizzando Tag Manager e Pixel Pixel. Quando importi gli eventi, devi fornire il timestamp nel campo eventTime nel formato specificato da RFC 3339.

Passaggi successivi