Esta página descreve os eventos do usuário para apps de pesquisa e recomendações, incluindo tipos, requisitos e exemplos de eventos do usuário.
Os seguintes tipos de app oferecem suporte a eventos do usuário:
- Apps de mídia: apps de pesquisa e recomendação de mídia. Para mais informações, consulte Sobre documentos de mídia e repositórios de dados.
- Apps genéricos: apps de pesquisa e recomendação que não são específicos para o setor. Para mais informações sobre o tipo de dados que compõem os apps genéricos, consulte Sobre apps e repositórios de dados.
A tabela a seguir lista os tipos de apps para os quais os eventos do usuário são necessários. O Google recomenda fazer upload de eventos do usuário para todos os tipos de app. Quanto mais eventos do usuário, melhor será a qualidade da pesquisa e das recomendações.
Tipo de app | Eventos do usuário obrigatórios? |
---|---|
Recomendações de mídia | Sim |
Pesquisa de mídia | Não, mas é altamente recomendado |
Recomendações genéricas | Não, mas é altamente recomendável |
Pesquisa genérica | Não, mas é altamente recomendável |
Para saber como gravar eventos do usuário, consulte Gravar eventos do usuário em tempo real.
Dependendo do tipo de app de pesquisa ou recomendações com que você está trabalhando, selecione uma das opções a seguir para conferir os detalhes dos eventos relevantes 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 pelo seu site:
Nome do evento do usuário | Ação do usuário |
---|---|
view-category-page |
Visualizar uma página de categoria, como Início > TV > Dramas, Início > Filmes > Ação. |
view-item |
Mostra os detalhes de um documento. |
view-home-page |
Visualiza a página inicial. |
search |
Pesquisa o repositório de dados. |
Para informações detalhadas sobre o objeto UserEvent
, consulte a
referência da API UserEvent
.
Exemplos e esquemas de tipo de evento do usuário
Esta seção apresenta os formatos de dados para cada tipo de evento compatível com as recomendações de mídia apps genéricos.
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 o desempenho. Os eventossearch
eview-item
gerados a partir de cliques de recomendações de mídiaprecisam 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
.
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
.
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
.
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" } ] } ] } ]
search
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 navegando, ou seja, clicando em categorias em vez de inserir uma consulta de texto.
documents
precisa incluir a lista de IDs de documentos 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
.
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 um usuário fizer login no site. Quando você grava o
userId
de um usuário,
os 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 seus 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 pelo RFC
3339.
A seguir
- Saiba como gravar eventos do usuário.