Informazioni sugli eventi utente per le app personalizzate

Nota: le app multimediali richiedono eventi utente diversi. Per informazioni, vedi Informazioni sugli eventi utente multimediali.

Questa pagina descrive gli eventi utente per le app di ricerca personalizzata e di suggerimenti, 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.

Google consiglia di caricare gli eventi almeno una volta al giorno per mantenere una buona qualità dei dati. Durante le importazioni di eventi storici, assicurati che la distribuzione dei dati sia orientata verso il timestamp più recente. Il numero di eventi nel giorno dell'ultimo timestamp deve essere uguale o superiore al conteggio medio giornaliero degli eventi.

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

Tipi di eventi utente

Puoi registrare i seguenti tipi di eventi utente quando gli utenti finali navigano o cercano 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 nell'app.

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

Esempi e schemi di tipi di eventi utente

Questa sezione fornisce i formati dei dati per ogni tipo di evento supportato da 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 esegui 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 suggerimenti devono avere un token di attribuzione per collegare gli eventi ai suggerimenti che li hanno generati.

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

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 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 degli 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 acquisiti,sono obbligatori almeno 250.000 elementi visualizzati.

Oggetto view-item minimo richiesto

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

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

• Quando acquisisci o registri eventi utente a livello di datastore, puoi fornire l'ID del documento (id) o il nome risorsa (name).
• Quando acquisisci o registri eventi a livello di località, devi fornire il nome risorsa del documento (name) perché indica il percorso completo di un documento e fa riferimento al datastore in cui risiede il documento. Puoi fornire l' ID del documento come informazioni aggiuntive facoltative.

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"
          }
        ]
      }
    ]
  }
]

Esempio di oggetto view-item completo

Gli esempi seguenti includono sia i campi obbligatori sia quelli facoltativi per il view-item evento utente.

Pixel JavaScript

var user_event = {
  eventType: "view-item",
  userPseudoId: "visitor0",
  "engine": "APP_ID",
  eventTime: "2020-01-01T03:33:33.000001Z",
  userInfo: {
    userId: "[e-mail]",
    userAgent: "Mozilla/5.0",
  },
  pageInfo: {
    pageViewId: "currentPageUri",
    uri: "http://example",
    referrerUri: "https://google",
  },
  attributionToken: "abcd",
  documents: [
    {
      id: "abcd",
    },
  ],
  tagIds: ["Treatment_B"],
  attributes: {
    example_text_attribute: {
      text: ["text_1", "text_2"],
    },
    example_number_attribute: {
      numbers: [3.14, 42, 1.2345],
    },
  },
  panels: [
         {
           panelId: "HOME_RFY_1",
           documents: [
             {
               id: "123"
             },
             {
               id: "456"
             }
           ],
           panelPosition: 1,
           totalPanels: 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": "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 è riportato il formato dell'evento utente view-home-page.

Oggetto view-home-page minimo richiesto

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

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

• Quando acquisisci o registri eventi utente a livello di datastore, puoi fornire l'ID del documento (id) o il nome risorsa (name).
• Quando acquisisci o registri eventi a livello di località, devi fornire il nome risorsa del documento (name) perché indica il percorso completo di un documento e fa riferimento al datastore in cui risiede il documento. Puoi fornire l' ID del documento come informazioni aggiuntive facoltative.

Pixel JavaScript

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_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 è 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": "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"
          }
        ]
      }
    ]
  }
]

Esempio di oggetto view-home-page completo

Gli esempi seguenti includono sia i campi obbligatori sia quelli facoltativi per l' view-home-page evento utente.

Pixel JavaScript

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "visitor0",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "userInfo": {
    "userId": "[e-mail]",
    "userAgent": "Mozilla/5.0",
  },
  "pageInfo": {
    "pageViewId": "currentPageUri",
    "uri": "http://example",
    "referrerUri": "https://google",
  },
  "attributionToken": "abcd",
  "documents": [
    {
      "id": "abcd",
      "quantity": 2,
    },
  ],
  "tagIds": ["Treatment_B"],
  "attributes": {
    "example_text_attribute": {
      "text": ["text_1", "text_2"],
    },
    "example_number_attribute": {
      "numbers": [3.14, 42, 1.2345],
    },
  },
  "panels": [
         {
           "panelId": "HOME_RFY_1",
           "documents": [
             {
               "id": "123"
             },
             {
               "id": "456"
             }
           ],
           "panelPosition": 1,
           "totalPanels": 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": "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"
          }
        ]
      }
    ]
  }
]

search

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

Requisiti di ottimizzazione della ricerca per gli eventi search

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 degli eventi	Volume/frequenza degli eventi	Descrizione
Volume di eventi search	100.000 ricerche	Per ottimizzare l'esperienza di ricerca in base agli eventi acquisiti,sono obbligatorie almeno 100.000 ricerche.

Oggetto search minimo richiesto

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

È obbligatorio specificare almeno un valore per il campo 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 verso gli elementi di interesse tramite la navigazione, ovvero facendo clic sulle categorie anziché inserendo una query di testo.

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

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

• Quando acquisisci o registri eventi utente a livello di datastore, puoi fornire l'ID del documento (id) o il nome risorsa (name).
• Quando acquisisci o registri eventi a livello di località, devi fornire il nome risorsa del documento (name) perché indica il percorso completo di un documento e fa riferimento al datastore in cui risiede il documento. Puoi fornire l' ID del documento come informazioni aggiuntive facoltative.

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",
  }, 
  "pageInfo": {
    "pageCategory": "CATEGORY_1 > CATEGORY_2",
  }, 
  "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 sugli utenti

userPseudoId 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 userPseudoId e, se disponibile, il valore userId. userId è facoltativo e può essere utilizzato come identificatore univoco e permanente per un utente su tutti i dispositivi ogni volta che un utente accede al tuo sito. Quando registri the userId per un utente, le tue app di ricerca e suggerimenti possono generare risultati più personalizzati per un utente su più dispositivi, ad esempio sia un dispositivo mobile sia un browser web.

Nota: utilizza una forma sicura di identificatore univoco per mantenere l'anonimato degli utenti in Ricerca agente e proteggere la privacy degli utenti. È tua responsabilità oscurare le informazioni che consentono l'identificazione personale (PII), come indirizzi email o di casa dai tuoi dati.

Informazioni sul timestamp

Quando registri un evento utente, assicurati di includere un timestamp accurato del momento in cui 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 eventTime campo nel formato specificato da RFC 3339.

Passaggi successivi

• Scopri come registrare gli eventi utente.