Acerca dos eventos do utilizador

Esta página descreve os eventos do utilizador para apps de pesquisa personalizada e recomendações, incluindo tipos de eventos do utilizador, requisitos e exemplos de tipos de eventos do utilizador.

Embora os eventos de utilizadores não sejam obrigatórios para apps personalizadas, são altamente recomendados.

Para obter ajuda com o registo de eventos do utilizador, consulte o artigo Registe eventos do utilizador em tempo real. Para importar eventos de utilizadores anteriores em massa, consulte o artigo Importe eventos de utilizadores históricos.

Tipos de eventos do utilizador

Pode registar os seguintes tipos de eventos do utilizador à medida que os utilizadores finais navegam ou pesquisam no seu site:

Nome do evento do utilizador Ação do utilizador
add-feedback Adiciona feedback dos utilizadores.
view-item-list Vê um painel ou uma lista ordenada de documentos.
view-item Ver detalhes de um documento.
view-home-page Visualiza a página inicial.
search Pesquisa na loja de dados.

Para ver detalhes sobre o objeto de evento do utilizador, consulte a UserEvent documentação de referência da API.

Exemplos e esquemas de tipos de eventos de utilizadores

Esta secção fornece os formatos de dados para cada tipo de evento suportado pelas apps personalizadas. São facultados exemplos do Pixel de JavaScript. Para o BigQuery, é fornecido o esquema completo da tabela para cada tipo.

Para todos os tipos de eventos de utilizador, userId é opcional.

Tenha em atenção que:

  • O campo tagIds só é necessário se estiver a executar uma experiência A/B.

  • O campo attributionToken é opcional e é usado para medir o desempenho. Os eventos search e view-item gerados a partir de cliques em recomendações devem ter um token de atribuição para associar os eventos às recomendações que os geraram.

Para mais detalhes sobre o objeto de evento do utilizador, consulte a UserEvent documentação de referência da API.

view_item

O exemplo seguinte mostra o formato dos dados de eventos do utilizador view-item.

Objeto view_item mínimo necessário

Os exemplos seguintes mostram apenas os campos obrigatórios do view-item formato de evento do utilizador.

Na maioria dos casos, documents contém detalhes do documento associado.

Píxel de JavaScript

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

BigQuery

Este é o esquema JSON completo para este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais estão definidos como NULLABLE.

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de data/hora. 

[
  {
    "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

O exemplo seguinte mostra o formato do evento de utilizador view-home-page.

Objeto view-home-page mínimo necessário

Os exemplos seguintes mostram apenas os campos obrigatórios do view-home-page formato de evento do utilizador.

Píxel de JavaScript

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

BigQuery

Este é o esquema JSON completo para este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais estão definidos como NULLABLE.

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de data/hora. 

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

O exemplo seguinte mostra o formato do evento de utilizador search.

Objeto de pesquisa mínimo necessário

Os exemplos seguintes mostram apenas os campos obrigatórios do formato de search evento de utilizador.

É necessário, pelo menos, um dos campos searchQuery ou pageCategory:

  • Forneça searchQuery para eventos de pesquisa em que o utilizador introduziu uma consulta de texto.

  • Forneça pageCategory quando o utilizador navegou para itens de interesse através da navegação, ou seja, clicando em categorias em vez de introduzir uma consulta de texto.

O elemento attributionToken é devolvido com a consulta de pesquisa ou os resultados da navegação.

documents deve incluir a lista de IDs dos documentos apresentados ao utilizador final na página de resultados da pesquisa.

Píxel de 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

Este é o esquema JSON completo para este tipo de evento de utilizador. Especifique este esquema quando criar tabelas para este tipo de evento do utilizador no BigQuery.

Os modos dos campos obrigatórios estão definidos como REQUIRED ou REPEATED. Os modos dos campos opcionais estão definidos como NULLABLE.

Tenha em atenção que o eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com um formato de data/hora. 

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

Acerca das informações do utilizador

userPseudoId representa o identificador único do utilizador e é obrigatório quando regista um evento do utilizador.

As informações do utilizador (UserInfo) incluídas quando regista um evento do utilizador contêm o valor userPseudoId e, se disponível, o valor userId. userId é opcional e pode ser usado como um identificador único e persistente de um utilizador em vários dispositivos sempre que um utilizador inicia sessão no seu site. Quando regista o userId para um utilizador, as suas apps de pesquisa e recomendações podem gerar resultados mais personalizados para um utilizador em vários dispositivos, como um dispositivo móvel e um navegador de Internet.

Acerca da indicação de tempo

Quando regista um evento do utilizador, certifique-se de que inclui uma indicação de tempo precisa de quando o evento ocorreu. As datas/horas precisas garantem que os seus eventos são armazenados pela ordem correta. As datas/horas são registadas automaticamente para eventos recolhidos através do píxel do JavaScript. Quando importa eventos, tem de indicar a data/hora no campo eventTime no formato especificado pela RFC 3339.

O que se segue?