Esta página descreve eventos do usuário para apps de música, incluindo eventos do usuário tipos, requisitos e exemplos de tipos de eventos do usuário.
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 receber ajuda com o registro de eventos do usuário, consulte Registre eventos do usuário em tempo real.
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 | Visualiza uma página de categoria, como "Página inicial" > 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 (link em inglês) | Clicar em "Reproduzir" em um item de mídia. |
media-complete (link em inglês) | 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 de eventos do usuário e práticas recomendadas para apps de música
As tabelas a seguir listam os requisitos e as práticas recomendadas para os tipos de evento do usuário usadas por apps de recomendações de mídia. Verifique se os eventos do usuário cumprem essas para que o app gere 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 de 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 de usuário são necessários para usar as recomendações de mídia. Outros são recomendados para melhorar os resultados, mas não são obrigatórios.
Prioridade | Eventos do usuário |
---|---|
Necessário para o experimento inicial em tempo real 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 seguintes requisitos para que seus Apps de recomendação de mídia podem 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 pode 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 pseudoIDs do usuário precisam ter o mesmo formato na importação de eventos de eventos, gravação de eventos e 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 seu repositório de dados. |
A proporção de eventos não associados deve ser a mais baixa possível. Uma alta proporção pode afetar negativamente a qualidade dos resultados. |
|
Alguns eventos de usuário precisam ter o mesmo pseudoID do usuário. |
Para criar históricos de sequência de comportamento válidos, os apps de recomendações de mídia precisam acessar 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 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 fornece os formatos de dados para cada tipo de evento suportado pelo recomendações de mídia.
Exemplos de pixels de JavaScript são fornecidos. 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. é usado para e medir o desempenho.search
eview-item
eventos gerados com base em recomendações de mídia cliques devem ter um token de atribuição para vincular os eventos de volta ao as recomendações que as 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
.
Mínimo necessário de "view-category-page"
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 um 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
.
Mínimo necessário de objetos de visualização do item
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 um 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
.
Mínimo necessário de objetos view-home-page
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 um 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
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
no 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
.
Mínimo necessário de objeto de reprodução de mídia
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
no BigQuery. eventTime
é uma string com um 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
no 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, é importante e também os inclua nos eventos de usuário associados às recomendações. solicitações. 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 Os apps de recomendação de mídia usam 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 exclusivo e persistente para um
o usuário em vários dispositivos sempre que ele 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 um dispositivo móvel 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 pixel do JavaScript. 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.