Informazioni sugli eventi utente

Questa pagina descrive gli eventi utente per le app Gemini Enterprise, inclusi i tipi di eventi utente, i requisiti e gli esempi di tipi di eventi utente.

Se utilizzi le API Gemini Enterprise nelle tue app, devi configurare la ricerca nell'app per ottenere gli eventi utente e poi aggiungere i dati sugli eventi utente all'app Gemini Enterprise.

Se crei la tua app tramite la consoleGoogle Cloud , non devi importare manualmente gli eventi utente (e non devi leggere questa pagina).

Per assistenza sulla registrazione degli eventi utente, consulta Registra gli eventi utente in tempo reale. Per importare in blocco gli eventi utente passati, consulta Importa gli eventi utente storici.

Tipi di eventi utente

Puoi registrare i seguenti tipi di eventi utente mentre gli utenti finali navigano o effettuano ricerche nel tuo sito:

Nome evento utente Azione dell'utente
view-item Visualizza i dettagli di un documento.
search Cerca i dati nell'app Gemini Enterprise.

Per informazioni dettagliate sull'oggetto evento utente, consulta la [documentazione di riferimento dell'API UserEvent][user-event].

Esempi e schemi di tipi di eventi utente

Questa sezione fornisce i formati dei dati per ogni tipo di evento supportato dalle app Gemini Enterprise. Vengono forniti esempi per il pixel JavaScript. Per BigQuery, viene fornito lo schema completo della tabella per ogni tipo.

Per tutti i tipi di eventi utente, userId è facoltativo.

Per maggiori dettagli sull'oggetto evento utente, consulta la [documentazione di riferimento dell'API UserEvent][user-event].

view-item

Di seguito è riportato il formato dei dati sugli eventi utente view-item.

Requisiti di ottimizzazione della ricerca per gli eventi view-item

Per consentire all'automazione degli annunci della rete di ricerca 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 ritardo massimo di 24 ore.

Metrica Eventi Volume/frequenza degli eventi Descrizione
Volume di eventi view-item 250.000 visualizzazioni di elementi

Sono necessari almeno 250.000 elementi di visualizzazione per ottimizzare l'esperienza di ricerca in base agli eventi importati.

Oggetto view-item minimo richiesto

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

L'oggetto documents contiene l'ID del documento (id) e il nome della risorsa (name).

  • Quando importi o registri gli eventi utente a livello di datastore, puoi fornire l'ID del documento (id) o il nome della risorsa (name).
  • Quando importi o registri eventi a livello di località, devi fornire il nome della risorsa del documento (name) perché indica il percorso completo di un documento e fa riferimento al datastore in cui si trova il documento. Puoi fornire l'ID del documento come informazione aggiuntiva facoltativa.

Pixel JavaScript

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "name": "DOCUMENT_NAME"
  }]
};

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 l'importazione di eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

Di seguito è riportato il formato dell'evento utente search.

Requisiti di ottimizzazione della ricerca per gli eventi di ricerca

Per consentire all'automazione degli annunci della rete di ricerca 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 ritardo massimo di 24 ore.

Metrica Eventi Volume/frequenza degli eventi Descrizione
Volume di eventi search 100.000 ricerche

Sono richieste almeno 100.000 ricerche per ottimizzare l'esperienza di ricerca in base agli eventi importati.

Oggetto di ricerca minimo richiesto

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

Fornisci searchQuery per gli eventi di ricerca in cui l'utente ha inserito una query di testo.

attributionToken viene restituito con i risultati della query di ricerca.

L'oggetto documents contiene l'ID del documento (id) e il nome della risorsa (name).

  • Quando importi o registri gli eventi utente a livello di datastore, puoi fornire l'ID del documento (id) o il nome della risorsa (name).
  • Quando importi o registri eventi a livello di località, devi fornire il nome della risorsa del documento (name) perché indica il percorso completo di un documento e fa riferimento al datastore in cui si trova il documento. Puoi fornire l'ID del documento come informazione aggiuntiva facoltativa.

Pixel JavaScript

var user_event = {
  "eventType": "search",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "searchInfo": {
    "searchQuery": "SEARCH_QUERY",
  }, 
  "attributionToken": "ATTRIBUTION_TOKEN",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1",
    },
    {
      "name": "DOCUMENT_NAME_2",
    },
  ]
};

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 l'importazione di eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

Informazioni utente

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

Le informazioni sull'utente ([UserInfo][user-info]) incluse quando registri un evento utente contengono il valore userPseudoId e, se disponibile, il valore userId. userId è facoltativo e può essere utilizzato come identificatore univoco e permanente di un utente su più dispositivi ogni volta che un utente è connesso al tuo sito. Quando registri la userId per un utente, le app Gemini Enterprise possono generare risultati più personalizzati per un 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 preciso di quando si è verificato l'evento. I timestamp accurati assicurano che gli eventi vengano archiviati nell'ordine corretto. I timestamp vengono registrati automaticamente per gli eventi raccolti utilizzando il pixel JavaScript. Quando importi gli eventi, devi fornire il timestamp nel campo [eventTime][event-time] nel formato specificato da RFC 3339.

[rec-type-reqs]: /gemini/enterprise/docs/about-media-recommendations-types [record-events]: /gemini/enterprise/docs/record-user-events [event-time]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents#UserEvent.FIELDS.event_time [user-event]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents [user-info]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents#userinfo