REST Resource: projects.locations.dataStores.userEvents

Risorsa: UserEvent

UserEvent acquisisce tutte le informazioni sui metadati che l'API Discovery Engine deve conoscere su come gli utenti finali interagiscono con il tuo sito web.

Rappresentazione JSON 
{
  "eventType": string,
  "conversionType": string,
  "userPseudoId": string,
  "engine": string,
  "dataStore": string,
  "eventTime": string,
  "userInfo": {
    object (UserInfo)
  },
  "directUserRequest": boolean,
  "sessionId": string,
  "pageInfo": {
    object (PageInfo)
  },
  "attributionToken": string,
  "filter": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panel": {
    object (PanelInfo)
  },
  "searchInfo": {
    object (SearchInfo)
  },
  "completionInfo": {
    object (CompletionInfo)
  },
  "transactionInfo": {
    object (TransactionInfo)
  },
  "tagIds": [
    string
  ],
  "promotionIds": [
    string
  ],
  "attributes": {
    string: {
      "text": [
        string
      ],
      "numbers": [
        number
      ]
    },
    ...
  },
  "mediaInfo": {
    object (MediaInfo)
  },
  "panels": [
    {
      object (PanelInfo)
    }
  ]
}
Campi
eventType

string

Obbligatorio. Tipo di evento utente. I valori consentiti sono:

Valori generici:

  • search: cerca documenti.
  • view-item: Visualizzazione dettagliata di una pagina di un documento.
  • view-item-list: Visualizzazione di un riquadro o di un elenco ordinato di documenti.
  • view-home-page: Visualizzazione della home page.
  • view-category-page: Visualizzazione di una pagina di categoria, ad es. Home > Uomo > Jeans

Valori correlati al retail:

  • add-to-cart: Aggiungi uno o più articoli al carrello, ad es. nello shopping online al dettaglio
  • purchase: Acquisto di uno o più articoli

Valori correlati ai media:

  • media-play: avvia/riprendi la riproduzione di un video, di un brano e così via.
  • media-complete: Ha terminato o interrotto a metà un video, un brano e così via.

Valore di conversione personalizzato:

  • conversion: evento di conversione definito dal cliente.
conversionType

string

Facoltativo. Tipo di conversione.

Obbligatorio se UserEvent.event_type è conversion. Si tratta di un nome di conversione definito dal cliente in lettere minuscole o numeri separati da "-", ad esempio "watch", "good-visit" e così via.

Non impostare il campo se UserEvent.event_type non è conversion. In questo modo, l'evento di conversione personalizzato viene combinato con eventi predefiniti come search, view-item e così via.
userPseudoId

string

Obbligatorio. Un identificatore univoco per il monitoraggio dei visitatori.

Ad esempio, questa operazione può essere implementata con un cookie HTTP, che dovrebbe essere in grado di identificare in modo univoco un visitatore su un singolo dispositivo. Questo identificatore univoco non deve cambiare se il visitatore esegue l'accesso o la disconnessione dal sito web.

Non impostare il campo sullo stesso ID fisso per utenti diversi. In questo modo, la cronologia degli eventi di questi utenti viene combinata, il che comporta una riduzione della qualità del modello.

Il campo deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 128 caratteri. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

Il campo non deve contenere PII o dati utente. Ti consigliamo di utilizzare l'ID client di Google Analytics per questo campo.
engine

string

Il nome della risorsa Engine, nel formato projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}.

Facoltativo. Richiesto solo per gli eventi utente prodotti da Engine. Ad esempio, gli eventi utente della ricerca ibrida.
dataStore

string

Il nome completo della risorsa DataStore, nel formato projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}.

Facoltativo. Obbligatorio solo per gli eventi utente il cui datastore non può essere determinato da UserEvent.engine o UserEvent.documents. Se il datastore è impostato nel parent delle richieste di scrittura/importazione/raccolta di eventi utente, questo campo può essere omesso.
eventTime

string (Timestamp format)

Obbligatorio solo per il metodo UserEventService.ImportUserEvents. Timestamp dell'evento utente.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
userInfo

object (UserInfo)

Informazioni sull'utente finale.
directUserRequest

boolean

Deve essere impostato su true se la richiesta viene effettuata direttamente dall'utente finale, nel qual caso UserEvent.user_info.user_agent può essere compilato dalla richiesta HTTP.

Questo flag deve essere impostato solo se la richiesta API viene effettuata direttamente dall'utente finale, ad esempio da un'app mobile (e non se un gateway o un server elabora e invia gli eventi utente).

Questo valore non deve essere impostato quando si utilizza il tag JavaScript in UserEventService.CollectUserEvent.
sessionId

string

Un identificatore univoco per monitorare una sessione di visitatore con un limite di lunghezza di 128 byte. Una sessione è un'aggregazione del comportamento di un utente finale in un periodo di tempo.

Una linea guida generale per compilare sessionId:

  1. Se l'utente non ha attività per 30 minuti, deve essere assegnato un nuovo sessionId.
  2. L'ID sessione deve essere univoco per tutti gli utenti. Ti consigliamo di utilizzare UUID o di aggiungere UserEvent.user_pseudo_id come prefisso.
pageInfo

object (PageInfo)

Metadati della pagina, come categorie e altre informazioni essenziali per determinati tipi di eventi, ad esempio view-category-page.
attributionToken

string

Token per attribuire una risposta API alle azioni utente per attivare l'evento.

Consigliato vivamente per gli eventi utente che sono il risultato di RecommendationService.Recommend. Questo campo consente un'attribuzione accurata del rendimento del modello di consigli.

Il valore deve essere uno dei seguenti:

Questo token ci consente di attribuire con precisione il completamento della visualizzazione di pagina o della conversione all'evento e alla risposta di previsione specifica contenente questo prodotto su cui è stato fatto clic/acquistato. Se l'utente fa clic sul prodotto K nei risultati dei consigli, trasmetti RecommendResponse.attribution_token come parametro URL alla pagina del prodotto K. Quando registri gli eventi nella pagina del prodotto K, inserisci RecommendResponse.attribution_token in questo campo.
filter

string

La sintassi del filtro è costituita da un linguaggio di espressione per costruire un predicato da uno o più campi dei documenti da filtrare.

Un esempio riguarda gli eventi search, il cui SearchRequest associato può contenere un'espressione di filtro in SearchRequest.filter conforme a https://google.aip.dev/160#filtering.

Allo stesso modo, per gli eventi view-item-list generati da un RecommendRequest, questo campo può essere compilato direttamente da RecommendRequest.filter in conformità con https://google.aip.dev/160#filtering.

Il valore deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 1000 caratteri. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
documents[]

object (DocumentInfo)

Elenco di Document associati a questo evento utente.

Questo campo è facoltativo, ad eccezione dei seguenti tipi di eventi:

  • view-item
  • add-to-cart
  • purchase
  • media-play
  • media-complete

In un evento search, questo campo rappresenta i documenti restituiti all'utente finale nella pagina corrente (l'utente finale potrebbe non aver ancora terminato di navigare l'intera pagina). Quando una nuova pagina viene restituita all'utente finale, dopo la paginazione/il filtraggio/l'ordinamento anche per la stessa query, è necessario un nuovo evento search con UserEvent.documents diversi.
panel

object (PanelInfo)

I metadati del panel associati a questo evento utente.
searchInfo

object (SearchInfo)

Dettagli di SearchService.Search relativi all'evento.

Questo campo deve essere impostato per l'evento search.
completionInfo

object (CompletionInfo)

Dettagli di CompletionService.CompleteQuery relativi all'evento.

Questo campo deve essere impostato per l'evento search quando la funzione di completamento automatico è attivata e l'utente fa clic su un suggerimento per la ricerca.
transactionInfo

object (TransactionInfo)

I metadati della transazione (se presenti) associati a questo evento utente.
tagIds[]

string

Un elenco di identificatori per i gruppi di esperimenti indipendenti a cui appartiene questo evento utente. Viene utilizzato per distinguere gli eventi utente associati a configurazioni di esperimenti diverse.
promotionIds[]

string

Gli ID promozione se si tratta di un evento associato alle promozioni. Al momento, questo campo è limitato a un solo ID.
attributes

map (key: string, value: object)

Funzionalità aggiuntive degli eventi utente da includere nel modello di suggerimento. Questi attributi NON devono contenere dati che devono essere analizzati o elaborati ulteriormente, ad esempio JSON o altre codifiche.

Se fornisci attributi personalizzati per gli eventi utente importati, includili anche negli eventi utente che associ 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 Discovery Engine può utilizzare questi attributi personalizzati durante l'addestramento dei modelli e la pubblicazione delle previsioni, il che contribuisce a migliorare la qualità dei suggerimenti.

Questo campo deve superare tutti i criteri riportati di seguito, altrimenti viene restituito un errore INVALID_ARGUMENT:

  • La chiave deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 5000 caratteri.
  • Per gli attributi di testo, sono consentiti al massimo 400 valori. Non sono consentiti valori vuoti. Ogni valore deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 256 caratteri.
  • Per gli attributi numerici, sono consentiti al massimo 400 valori.

Per i consigli sui prodotti, un esempio di informazioni aggiuntive sull'utente è traffic_channel, ovvero il modo in cui un utente arriva al sito. Gli utenti possono arrivare al sito direttamente, tramite la Ricerca Google o in altri modi.
attributes.text[]

string

I valori testuali di questo attributo personalizzato. Ad esempio, ["yellow", "green"] quando la chiave è "colore".

Non è consentita una stringa vuota. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

Deve essere impostato esattamente uno dei valori CustomAttribute.text o CustomAttribute.numbers. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
attributes.numbers[]

number

I valori numerici di questo attributo personalizzato. Ad esempio, [2.3, 15.4] quando la chiave è "lengths_cm".

Deve essere impostato esattamente uno dei valori CustomAttribute.text o CustomAttribute.numbers. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
mediaInfo

object (MediaInfo)

Informazioni specifiche per i contenuti multimediali.
panels[]

object (PanelInfo)

Facoltativo. Elenco dei panel associati a questo evento. Utilizzato per i dati sulle impressioni a livello di pagina.

UserInfo

Informazioni di un utente finale.

Rappresentazione JSON 
{
  "userId": string,
  "userAgent": string,
  "timeZone": string
}
Campi
userId

string

Consigliato vivamente per gli utenti che hanno eseguito l'accesso. Identificatore univoco dell'utente che ha eseguito l'accesso, ad esempio un nome utente. Non impostare per gli utenti anonimi.

Utilizza sempre un valore sottoposto ad hashing per questo ID.

Non impostare il campo sullo stesso ID fisso per utenti diversi. In questo modo, la cronologia degli eventi di questi utenti viene combinata, il che comporta una riduzione della qualità del modello.

Il campo deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 128 caratteri. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
userAgent

string

User agent incluso nell'intestazione HTTP.

Il campo deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 1000 caratteri. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

Questo valore non deve essere impostato quando utilizzi la generazione di report sugli eventi lato client con GTM o il tag JavaScript in UserEventService.CollectUserEvent o se è impostato UserEvent.direct_user_request.
timeZone

string

Facoltativo. Fuso orario IANA, ad es. Europe/Budapest.

PageInfo

Informazioni dettagliate sulla pagina.

Rappresentazione JSON 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
Campi
pageviewId

string

Un ID univoco di una visualizzazione di una pagina web.

Questo valore deve rimanere invariato per tutti gli eventi utente attivati dalla stessa visualizzazione di pagina. Ad esempio, una visualizzazione della pagina dei dettagli di un elemento potrebbe attivare più eventi mentre l'utente naviga nella pagina. La proprietà pageviewId deve rimanere invariata per tutti questi eventi in modo che possano essere raggruppati correttamente.

Quando utilizzi i report sugli eventi lato client con il pixel JavaScript e Google Tag Manager, questo valore viene compilato automaticamente.
pageCategory

string

La categoria più specifica associata a una pagina di categoria.

Per rappresentare il percorso completo della categoria, utilizza il simbolo ">" per separare le diverse gerarchie. Se ">" fa parte del nome della categoria, sostituiscilo con altri caratteri.

Le pagine delle categorie includono pagine speciali come vendite o promozioni. Ad esempio, una pagina di vendita speciale potrebbe avere la gerarchia di categorie: "pageCategory" : "Sales > 2017 Black Friday Deals".

Obbligatorio per gli eventi view-category-page. Gli altri tipi di eventi non devono impostare questo campo. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
uri

string

L'URL completo (window.location.href) della pagina corrente dell'utente.

Quando utilizzi i report sugli eventi lato client con il pixel JavaScript e Google Tag Manager, questo valore viene compilato automaticamente. La lunghezza massima è di 5000 caratteri.
referrerUri

string

L'URL referrer della pagina corrente.

Quando utilizzi i report sugli eventi lato client con il pixel JavaScript e Google Tag Manager, questo valore viene compilato automaticamente. Tuttavia, alcune limitazioni della privacy del browser potrebbero causare la visualizzazione di questo campo vuoto.

DocumentInfo

Informazioni dettagliate sul documento associate a un evento utente.

Rappresentazione JSON 
{
  "promotionIds": [
    string
  ],
  "joined": boolean,

  // Union field document_descriptor can be only one of the following:
  "id": string,
  "name": string,
  "uri": string
  // End of list of possible types for union field document_descriptor.
  "quantity": integer,
  "conversionValue": number
}
Campi
promotionIds[]

string

Gli ID promozione associati a questo documento. Al momento, questo campo è limitato a un solo ID.
joined

boolean

Solo output. Se il documento a cui viene fatto riferimento è presente nel datastore.

Campo unione document_descriptor. Un descrittore obbligatorio del Document associato.

  • Se viene specificato id, vengono utilizzati i valori predefiniti per {location}, {collection_id}, {data_store_id} e {branch_id} durante l'annotazione con il documento archiviato.

  • Se viene specificato name, i valori forniti (valori predefiniti consentiti) per {location}, {collection_id}, {data_store_id} e {branch_id} vengono utilizzati per l'annotazione con il documento archiviato. document_descriptor può essere solo uno dei seguenti:
id

string

L'ID risorsa Document.
name

string

Il nome completo della risorsa Document, nel formato: projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}
uri

string

L'URI Document, consentito solo per i datastore di siti web.
quantity

integer

Quantità del documento associato all'evento utente. Il valore predefinito è 1.

Ad esempio, questo campo è 2 se due quantità dello stesso documento sono coinvolte in un evento add-to-cart.

Obbligatorio per gli eventi dei seguenti tipi di evento:

  • add-to-cart
  • purchase
conversionValue

number

Facoltativo. Il valore di conversione associato a questo documento. Deve essere impostato se UserEvent.event_type è "conversione".

Ad esempio, un valore di 1000 indica che sono stati trascorsi 1000 secondi per la visualizzazione di un documento per il tipo di conversione watch.

PanelInfo

Informazioni dettagliate del pannello associate a un evento utente.

Rappresentazione JSON 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
Campi
panelId

string

Obbligatorio. L'ID del riquadro.
displayName

string

Il nome visualizzato del riquadro.
documents[]

object (DocumentInfo)

Facoltativo. Gli ID documento associati a questo riquadro.
panelPosition

integer

La posizione ordinata del pannello, se mostrato all'utente insieme ad altri pannelli. Se impostato, deve essere impostato anche totalPanels.
totalPanels

integer

Il numero totale di riquadri, incluso questo, mostrati all'utente. Deve essere impostato se panelPosition è impostato.

SearchInfo

Informazioni dettagliate sulla ricerca.

Rappresentazione JSON 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
Campi
searchQuery

string

La query di ricerca dell'utente.

Per la definizione, vedi SearchRequest.query.

Il valore deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 5000 caratteri. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

È obbligatorio specificare almeno un valore per searchQuery o PageInfo.page_category per gli eventi search. Gli altri tipi di eventi non devono impostare questo campo. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
orderBy

string

L'ordine in cui vengono restituiti i prodotti, se applicabile.

Consulta SearchRequest.order_by per la definizione e la sintassi.

Il valore deve essere una stringa codificata in UTF-8 con un limite di lunghezza di 1000 caratteri. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

Può essere impostato solo per gli eventi search. Gli altri tipi di eventi non devono impostare questo campo. In caso contrario, viene restituito un errore INVALID_ARGUMENT.
offset

integer

Un numero intero che specifica l'offset corrente per la paginazione (la posizione iniziale con indice 0 tra i prodotti ritenuti pertinenti dall'API).

Per la definizione, vedi SearchRequest.offset.

Se questo campo è negativo, viene restituito un INVALID_ARGUMENT.

Può essere impostato solo per gli eventi search. Gli altri tipi di eventi non devono impostare questo campo. In caso contrario, viene restituito un errore INVALID_ARGUMENT.

CompletionInfo

Informazioni dettagliate sul completamento, tra cui il token di attribuzione del completamento e le informazioni sul completamento dei clic.

Rappresentazione JSON 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
Campi
selectedSuggestion

string

Utente finale selezionato CompleteQueryResponse.QuerySuggestion.suggestion.
selectedPosition

integer

Posizione CompleteQueryResponse.QuerySuggestion.suggestion selezionata dall'utente finale, a partire da 0.

TransactionInfo

Una transazione rappresenta l'intera transazione di acquisto.

Rappresentazione JSON 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
Campi
currency

string

Obbligatorio. Codice valuta. Utilizza il codice ISO-4217 di tre caratteri.
transactionId

string

L'ID transazione con un limite di lunghezza di 128 caratteri.
value

number

Obbligatorio. Valore totale diverso da zero associato alla transazione. Questo valore può includere spedizione, tasse o altri aggiustamenti al valore totale da includere.
tax

number

Tutte le imposte associate alla transazione.
cost

number

Tutti i costi associati ai prodotti. Questi possono essere costi di produzione, spese di spedizione non sostenute dall'utente finale o altri costi, in modo che:
discountValue

number

Il valore totale degli sconti applicati a questa transazione. Questa cifra deve essere esclusa da TransactionInfo.value

Ad esempio, se un utente ha pagato l'importo TransactionInfo.value, il valore nominale (pre-sconto) della transazione è la somma di TransactionInfo.value e TransactionInfo.discount_value

Ciò significa che il profitto viene calcolato allo stesso modo, indipendentemente dal valore dello sconto, e che TransactionInfo.discount_value può essere maggiore di TransactionInfo.value:

MediaInfo

Informazioni sugli eventi utente specifici per i contenuti multimediali.

Rappresentazione JSON 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
Campi
mediaProgressDuration

string (Duration format)

Il tempo di avanzamento dei contenuti multimediali in secondi, se applicabile. Ad esempio, se l'utente finale ha terminato 90 secondi di un video di riproduzione, MediaInfo.media_progress_duration.seconds deve essere impostato su 90.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
mediaProgressPercentage

number

L'avanzamento dei contenuti multimediali deve essere calcolato utilizzando solo mediaProgressDuration rispetto alla durata totale dei contenuti multimediali.

Questo valore deve essere compreso tra [0, 1.0] inclusi.

Se non si tratta di una riproduzione o se non è possibile calcolare i progressi (ad es. live streaming in corso), questo campo deve essere deselezionato.

Metodi

collect

 Scrive un singolo evento utente dal browser.

import

 Importazione collettiva di eventi utente.

purge

 Elimina definitivamente tutti gli eventi utente specificati dal filtro fornito.

write

 Scrive un singolo evento utente.