Informazioni sugli eventi utente

Questa pagina descrive gli eventi utente per le app di ricerca e consigli personalizzati, inclusi i tipi di eventi utente, i requisiti e gli esempi per i tipi di eventi utente.

Sebbene gli eventi utente non siano obbligatori per le app personalizzate, sono altamente consigliati.

Per mantenere una buona qualità dei dati, è consigliabile caricare gli eventi almeno una volta al giorno. Durante le importazioni di eventi storici, assicurati che la distribuzione dei dati sia sbilanciata verso il timestamp più recente. Il numero di eventi nell'ultimo giorno del timestamp deve essere uguale o superiore al conteggio medio giornaliero degli eventi.

Per assistenza con la registrazione degli eventi utente, consulta Registra gli eventi utente in tempo reale. Per importare in blocco gli eventi utente passati, consulta Importare gli eventi utente storici.

Tipi di eventi utente

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

Nome evento utente Azione dell'utente
view-item-list Visualizza un riquadro o un elenco ordinato di documenti.
view-item Visualizza i dettagli di un documento.
view-home-page Visualizza la home page.
search Cerca nel datastore.

Per informazioni dettagliate sull'oggetto evento utente, consulta la documentazione di riferimento dell'API UserEvent.

Esempi e schemi di tipi di eventi utente

Questa sezione fornisce i formati dei dati per ogni tipo di evento supportato dalle app personalizzate. 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.

Ricorda:

  • Il campo tagIds è necessario solo se stai eseguendo un esperimento A/B.

  • Il campo attributionToken è facoltativo e viene utilizzato per misurare il rendimento. Gli eventi search e view-item generati dai clic sui consigli devono avere un token di attribuzione per collegare gli eventi ai consigli che li hanno generati.

Per ulteriori dettagli sull'oggetto evento utente, consulta la documentazione di riferimento dell'API UserEvent.

view-item

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

Requisiti di ottimizzazione della rete di ricerca per gli eventi visualizza articolo

Per consentire alla 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 elementi visualizzati

Per ottimizzare l'esperienza di ricerca in base agli eventi importati,sono necessari almeno 250.000 elementi di visualizzazione.

Oggetto visualizza elemento minimo richiesto

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

Nella maggior parte dei casi, documents contiene i dettagli del documento associato.

Pixel JavaScript

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "id": "document-id"
  }]
};

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 è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "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"
          }
        ]
      }
    ]
  }
]

view-home-page

Di seguito viene mostrato il formato dell'evento utente view-home-page.

Oggetto visualizza-home-page minimo richiesto

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

Pixel JavaScript

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
};

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 è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "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": "quantity",
        "type": "INT64",
        "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 viene mostrato il formato dell'evento utente search.

Requisiti di ottimizzazione della ricerca per gli eventi di ricerca

Per consentire alla 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

Per ottimizzare l'esperienza di ricerca in base agli eventi importati,sono necessarie almeno 100.000 ricerche.

Oggetto di ricerca minimo richiesto

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

È obbligatorio specificare almeno un campo tra searchQuery e pageCategory:

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

  • Fornisci pageCategory quando l'utente ha navigato tra gli elementi di interesse sfogliando, ovvero facendo clic sulle categorie anziché inserendo una query di testo.

Il attributionToken viene restituito con la query di ricerca o i risultati di navigazione.

documents deve includere l'elenco degli ID documento mostrati all'utente finale nella pagina dei risultati di ricerca.

Pixel JavaScript

var user_event = {
  eventType: "search",
  userPseudoId: "user-pseudo-id",
  eventTime: "2020-01-01T03:33:33.000001Z",
  searchInfo: {
    searchQuery: "search-query",
  }, 
  pageInfo: {
    pageCategory: "category1 > category2",
  }, 
  attributionToken: "attribution-token",
  documents: [
    {
      id: "document-id1",
    },
    {
      id: "document-id2",
    },
  ]
};

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 è necessario per importare eventi con BigQuery. eventTime è una stringa con un formato timestamp. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "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 sull'utente

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

Le informazioni utente (UserInfo) 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 per un utente su più dispositivi ogni volta che un utente accede al tuo sito. Quando registri l'userId per un utente, le tue app di ricerca e consigli 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 del momento in cui si è verificato l'evento. Timestamp accurati assicurano che gli eventi vengano memorizzati 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 nel formato specificato da RFC 3339.

Passaggi successivi