Esta página descreve os eventos do usuário para apps de mídia, incluindo tipos de evento do usuário, requisitos e exemplos.
A gravação de eventos do usuário é necessária para apps de recomendações de mídia. Os apps de recomendações de mídia usam eventos do usuário em tempo real para gerar recomendações. Outros tipos de apps não exigem eventos do usuário.
A tabela a seguir lista os tipos de app para fazer upload de eventos do usuário:
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 |
Pesquisa genérica | Não, mas é altamente recomendado |
Para saber como gravar eventos do usuário, consulte Gravar eventos do usuário em tempo real.
Tipos de evento do usuário
Você pode registrar os seguintes tipos de eventos de usuário conforme 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 | Abre a página de detalhes de um documento. |
view-home-page | Exibe a página inicial. |
search | Pesquisa o repositório de dados. |
media-play | Clicar em "Reproduzir" em um item de mídia. |
media-complete | Interrompe a reprodução de um item de mídia, indicando o fim da exibição. |
Para informações detalhadas sobre o objeto UserEvent
, consulte a
referência da API UserEvent
.
Requisitos e práticas recomendadas para eventos do usuário em apps de mídia
As tabelas a seguir listam os requisitos e as práticas recomendadas para tipos de evento do usuário usados pelos apps de recomendações de mídia. Verifique se os eventos do usuário atendem a esses requisitos para que o app possa gerar resultados de qualidade.
Consulte também Sobre os tipos de recomendações de apps de mídia, que lista os tipos de eventos do usuário necessários dependendo do tipo de recomendação e do objetivo de otimização que você pretende usar.
Prioridade do tipo de evento para recomendações de mídia
A tabela a seguir descreve a prioridade dos tipos de eventos do usuário para recomendações de mídia. Alguns eventos do usuário são necessários para usar as recomendações de mídia. Outros são recomendados para melhorar seus resultados, mas não são obrigatórios.
Prioridade | Eventos do usuário |
---|---|
Obrigatório para o experimento dinâmico inicial com recomendações de mídia | |
Importante para melhorar a qualidade dos resultados das recomendações de mídia ao longo do tempo |
Requisitos de recomendações de mídia
Verifique se os eventos do usuário atendem aos requisitos a seguir para que os apps de recomendações de mídia possam gerar resultados de qualidade.
Tipo de evento | Requisito | Impacto |
---|---|---|
Todos os eventos |
Não inclua dados sintéticos ou eventos duplicados. |
Eventos sintéticos ou duplicados afetam negativamente a qualidade dos resultados e podem impedir a implantação do app. Eventos duplicados podem causar valores de métricas incorretos. |
Inclua pelo menos 100 pseudoIDs de usuários únicos para cada tipo de evento processado. |
Isso garante que os apps de recomendações de mídia tenham dados suficientes para gerar resultados de qualidade. |
|
Os pseudo-IDs do usuário precisam ter a mesma formatação na importação ou gravação de eventos e nas solicitações de recomendações de mídia. |
Usar um formato consistente para pseudo-IDs de usuários ajuda os apps de recomendações de mídia a identificar corretamente os padrões de visitantes e a fornecer resultados de melhor qualidade com base no comportamento do usuário. |
|
O campo |
Um evento que inclui um documento sem um campo |
|
Os documentos incluídos nos eventos precisam existir no repositório de dados. |
A proporção de eventos não associados deve ser a mais baixa possível. Uma proporção alta pode afetar negativamente a qualidade dos resultados. |
|
Alguns eventos de usuário precisam ter o mesmo pseudo-ID. |
Para criar históricos de sequência de comportamento válidos, os apps de recomendações de mídia precisam ter acesso a vários eventos com o mesmo pseudo-ID do usuário.
Por exemplo, |
|
view-item |
Inclua exatamente um documento por evento. |
O evento não pode ser usado se não houver um documento. Se vários documentos forem incluídos, o evento será considerado incorreto e não poderá ser usado. |
media-play |
Inclua exatamente um documento por evento. |
Se vários documentos forem incluídos, o evento será considerado incorreto e não poderá ser usado. |
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.
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.
Observaçõ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 em recomendações de mídia 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
.
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", }, 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": "documents", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" } ] } ]
media-play
Veja a seguir o formato de evento do usuário media-play
.
Objeto media-play mínimo necessário
Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento
do usuário media-play
.
JavaScript Pixel
var user_event = { "eventType": "media-play", "userPseudoId": "user-pseudo-id", "eventTime": "2020-01-01T03:33:33.000001Z", "documents": [ { "id": "document-id1" } ] };
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" } ] } ] } ]
media-complete
Veja a seguir o formato de evento do usuário media-complete
.
Objeto media-complete mínimo necessário
Os exemplos a seguir mostram apenas os campos obrigatórios para o formato de evento
do usuário media-complete
.
JavaScript Pixel
var user_event = { "eventType": "media-complete", "userPseudoId": "user-pseudo-id", "eventTime": "2020-01-01T03:33:33.000001Z", "documents": [ { "id": "document-id1" } ], "mediaInfo": { "mediaProgressDuration": "65s", "mediaProgressPercentage": 1.2 } };
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" } ] } ] }, { "name": "mediaInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "mediaProgressDuration", "type": "STRING", "mode": "NULLABLE" }, { "name": "mediaProgressPercentage", "type": "NUMERIC", "mode": "NULLABLE" } ] } ]
Atributos personalizados
É possível incluir outros atributos e recursos personalizados para eventos do usuário. Isso
pode resultar em recomendações melhores e mais específicas para seus usuários quando você
usa recomendações de mídia. Para adicionar atributos personalizados, use attributes
ao
registrar um evento do usuário.
Se você fornecer atributos personalizados para eventos de usuário ingeridos, também é importante incluí-los nos eventos de usuário associados a solicitações de recomendação. A formatação dos atributos personalizados precisa ser consistente entre os eventos importados e os eventos fornecidos com solicitações de recomendação. Isso permite que apps de recomendações de mídia usem esses atributos personalizados para melhorar a qualidade.
Você pode fornecer valores de texto personalizados usando o campo text
ou valores
numéricos personalizados usando o campo numbers
.
Por exemplo, a seguir é mostrada a seção attributes
de uma solicitação
para gravar um evento do usuário:
attributes: { user_age: {text: ["teen", "young adult"]}, user_location: {text: ["CA"]}, user_zip: {numbers: [90210]} }
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 recomendação de mídia 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.