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.

Recomendamos que carregue eventos, pelo menos, diariamente para manter uma boa qualidade de dados. Durante as importações de eventos de histórico, certifique-se de que a distribuição de dados é enviesada para a data/hora mais recente. O número de eventos no último dia de data/hora deve ser igual ou superior à contagem média de eventos diários.

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
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 no arquivo 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 por 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.

Requisitos de otimização da pesquisa para eventos view_item

Para permitir que a pesquisa otimize automaticamente a experiência de pesquisa com base nas tendências gerais dos utilizadores, carregue os seguintes dados.

Os eventos devem ser carregados, pelo menos, diariamente, com um atraso máximo de 24 horas.

Métrica de eventos Volume/frequência de eventos Descrição
Volume de eventos do tipo view-item 250 mil itens visualizados

São necessários, pelo menos, 250 000 itens de visualização para otimizar a experiência de pesquisa com base nos eventos carregados.

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.

Requisitos de otimização da pesquisa para eventos de pesquisa

Para permitir que a pesquisa otimize automaticamente a experiência de pesquisa com base nas tendências gerais dos utilizadores, carregue os seguintes dados.

Os eventos devem ser carregados, pelo menos, diariamente, com um atraso máximo de 24 horas.

Métrica de eventos Volume/frequência de eventos Descrição
Volume de eventos do tipo search 100 mil pesquisas

São necessárias, pelo menos, 100 000 pesquisas para otimizar a experiência de pesquisa com base nos eventos carregados.

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.

  • Indique pageCategory quando o utilizador navegou para artigos 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 fornecer a data/hora no campo eventTime no formato especificado pela RFC 3339.

O que se segue?