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 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
add-feedback Aggiunge il feedback degli utenti.
view-item-list Visualizza un riquadro o un elenco ordinato di documenti.
view-category-page Visualizza una pagina di categoria, ad esempio Home > TV > Drammi, Home > Film > Azione.
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-category-page

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

Oggetto view-category-page minimo richiesto

Gli esempi riportati di seguito mostrano solo i campi obbligatori del formato dell'evento utente view-category-page.

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

Pixel JavaScript

var user_event = {
  "eventType": "view-category-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "pageInfo": {
    "pageCategory": "category1 > category2"
  }
};

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": "pageCategory",
        "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-item

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

Oggetto visualizzazione articolo minimo richiesto

Gli esempi riportati di seguito 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 riportati di seguito 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.

Oggetto di ricerca minimo richiesto

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

È obbligatorio specificare almeno un valore per searchQuery o 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 accurato 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