Sobre os eventos do usuário

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

Embora não sejam obrigatórios para apps personalizados, os eventos do usuário são altamente recomendados.

Para ajuda com a gravação de eventos do usuário, consulte Registrar eventos do usuário em tempo real. Para importar eventos anteriores do usuário em massa, consulte Importar eventos históricos do usuário.

Tipos de evento do usuário

Você pode registrar os seguintes tipos de eventos de usuário enquanto os usuários finais navegam ou pesquisam no seu site:

Nome do evento do usuário Ação do usuário
add-feedback Adiciona feedback do usuário.
view-item-list Mostra um painel ou uma lista ordenada de documentos.
view-category-page Acessa uma página de categoria, como Início > TV > Dramas ou Início > Filmes > Ação.
view-item Mostra os detalhes de um documento.
view-home-page Acessa a página inicial.
search Pesquisa no repositório de dados.

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

Exemplos e esquemas de tipo de evento do usuário

Nesta seção, apresentamos os formatos de dados para cada tipo de evento compatível com apps personalizados. São fornecidos exemplos do JavaScript Pixel. Para o BigQuery, é fornecido o esquema de tabela completo para cada tipo.

Para todos os tipos de eventos do usuário, userId é opcional.

Algumas considerações:

  • O campo tagIds é necessário somente se você estiver executando um experimento A/B.

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

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

view-category-page

Veja a seguir o formato de evento do usuário view-category-page.

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

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário view-category-page.

Embora geralmente haja apenas uma categoria associada a uma página, o campo pageCategories também é compatível com uma hierarquia de categorias, que pode ser fornecida em forma de lista.

JavaScript Pixel

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

BigQuery

Este é o esquema JSON completo para esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

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

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com o formato de carimbo 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": "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

Veja a seguir o formato de dados de evento do usuário view-item.

Objeto view-item mínimo necessário

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário view-item.

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

JavaScript Pixel

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 esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

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

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com o formato de carimbo 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

Veja a seguir o formato de evento do usuário view-home-page.

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

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário view-home-page.

JavaScript Pixel

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 esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

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

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com o formato de carimbo 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"
          }
        ]
      }
    ]
  }
]

Veja a seguir o formato de evento do usuário search.

Objeto search mínimo necessário

Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento do usuário search.

Pelo menos um dos campos searchQuery ou pageCategory é obrigatório:

  • Forneça searchQuery para eventos de pesquisa em que o usuário inseriu uma consulta de texto.

  • Forneça pageCategory quando o usuário navegar até itens de interesse por navegação, ou seja, clicando em categorias em vez de inserir uma consulta de texto.

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

documents precisa incluir a lista de IDs de documento mostrados ao usuário final na página de resultados da pesquisa.

JavaScript Pixel

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 esse tipo de evento do usuário. Especifique esse esquema ao criar tabelas para esse tipo de evento do usuário no BigQuery.

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

Observe que eventTime é necessário para importar eventos com o BigQuery. eventTime é uma string com o formato de carimbo 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"
      }
    ]
  }
]

Sobre as informações do usuário

userPseudoId representa o identificador de usuário único e é necessário para registrar um evento do usuário.

As informações do usuário (UserInfo) incluídas quando você registra um evento do usuário contêm o valor userPseudoId e, se disponível, o valor userId. userId é opcional e pode ser usado como um identificador permanente e exclusivo de um usuário em vários dispositivos sempre que ele faz login no site. Quando você grava o userId de um usuário, seus apps de pesquisa e recomendação podem gerar resultados mais personalizados para um usuário em vários dispositivos, como dispositivos móveis e um navegador da Web.

Sobre o carimbo de data/hora

Ao registrar um evento do usuário, inclua um carimbo de data/hora preciso de quando o evento ocorreu. Carimbos de data/hora precisos garantem que os eventos sejam armazenados na ordem correta. Os carimbos de data/hora são registrados automaticamente para eventos coletados usando o JavaScript Pixel. Ao importar eventos, é necessário informar o carimbo de data/hora no campo eventTime no formato especificado pela RFC 3339.

A seguir