En esta página, se describen los eventos de usuario de las apps de música, incluidos los tipos de eventos de usuario, los requisitos y los ejemplos de estos tipos.
La grabación de eventos de usuario es obligatoria para las apps de recomendaciones de contenido multimedia. Las apps de recomendaciones de contenido multimedia usan eventos de usuario en tiempo real para generar recomendaciones. Otros tipos de aplicaciones no requieren eventos de usuario.
En la siguiente tabla, se indican los tipos de apps para los que debes subir eventos del usuario:
| Tipo de app | ¿Se requieren eventos de usuario? |
|---|---|
| Recomendaciones de contenido multimedia | Sí |
| Búsqueda de contenido multimedia | No, pero se recomienda |
| Recomendaciones genéricas | No |
| Búsqueda genérica | No, pero se recomienda |
Para obtener ayuda con el registro de eventos de usuario, consulta Registra eventos de usuarios en tiempo real.
Tipos de eventos del usuario
Puedes registrar los siguientes tipos de eventos de usuario a medida que los usuarios finales exploran tu sitio:
| Nombre del evento del usuario | Acción del usuario |
|---|---|
| view-category-page | Ve una página de categoría, como Página principal > TV > Dramas o Página principal > Películas > Acción. |
| view-item | Visualiza la página de detalles de un documento. |
| view-home-page | Visualiza la página principal. |
| búsqueda | Busca en el almacén de datos. |
| media-play | Clics para reproducir en un elemento multimedia |
| media-complete | Detiene la reproducción de un elemento multimedia, lo que indica que se terminó de mirar. |
Para obtener información detallada sobre el objeto UserEvent, consulta la
referencia de la API de UserEvent.
Requisitos y prácticas recomendadas para eventos de usuario de apps de música
En las siguientes tablas, se enumeran los requisitos y las prácticas recomendadas para los tipos de eventos de usuario que usan las apps de recomendaciones de contenido multimedia. Verifica que tus eventos de usuario cumplan con estos requisitos para que tu app pueda generar resultados de calidad.
Consulta también Acerca de los tipos de recomendaciones de apps de música, en el que se enumeran los tipos de eventos del usuario necesarios según el tipo de recomendación y el objetivo de optimización que planeas usar.
Prioridad del tipo de evento para las recomendaciones de contenido multimedia
En la siguiente tabla, se describe la prioridad de los tipos de eventos del usuario para las recomendaciones de contenido multimedia. Algunos eventos del usuario son obligatorios para usar las recomendaciones de contenido multimedia. Otros se recomiendan para mejorar tus resultados, pero no son obligatorios.
| Prioridad | Eventos del usuario |
|---|---|
| Obligatorio para el experimento inicial en vivo con recomendaciones de contenido multimedia | |
| Importante para mejorar la calidad de los resultados de las recomendaciones de contenido multimedia a lo largo del tiempo |
Requisitos de las recomendaciones de contenido multimedia
Asegúrate de que tus eventos de usuario cumplan con los siguientes requisitos para que tus apps de recomendaciones de contenido multimedia puedan generar resultados de calidad.
| Tipo de evento | Requisito | Impacto |
|---|---|---|
| Todos los eventos |
No incluyas datos sintéticos ni eventos duplicados. |
Los eventos duplicados o sintéticos afectan de forma negativa la calidad de los resultados y pueden impedir que implementes tu app. Los eventos duplicados pueden causar valores de métricas incorrectos. |
|
Incluye al menos 100 seudo-IDs de usuario únicos para cada tipo de evento transferido. |
Esto garantiza que las apps de recomendaciones de contenido multimedia tengan suficientes datos para generar resultados de calidad. |
|
|
Los seudo-IDs de usuario deben tener el mismo formato en la importación de eventos o su registro, y en las solicitudes de recomendaciones de contenido multimedia. |
El uso de un formato coherente para los seudo-IDs de los usuarios ayuda a las apps de recomendaciones de contenido multimedia a identificar correctamente los patrones de los visitantes y a proporcionar resultados de mejor calidad en función del comportamiento de los usuarios. |
|
|
El campo |
Las apps de recomendaciones de contenido multimedia no pueden usar un evento que incluya un documento sin un campo |
|
|
Los documentos incluidos en los eventos deben existir en tu almacén de datos. |
La proporción de eventos no unidos debe mantenerse lo más baja posible. Una proporción alta puede tener un impacto negativo en la calidad de los resultados. |
|
|
Algunos eventos de usuario deben tener el mismo seudo-ID de usuario. |
Para construir historiales de secuencias de comportamiento válidos, las apps de recomendaciones de contenido multimedia deben poder ver varios eventos con el mismo seudo-ID del usuario.
Por ejemplo, |
|
view-item |
Incluye exactamente un documento por evento. |
No se puede usar el evento si no existe ningún documento. Si se incluyen varios documentos, el evento tiene un formato incorrecto y no se puede usar. |
media-play |
Incluye exactamente un documento por evento. |
Si se incluyen varios documentos, el evento tiene un formato incorrecto y no se puede usar. |
Ejemplos y esquemas de los tipos de eventos del usuario
En esta sección, se proporcionan los formatos de datos para cada tipo de evento que admiten las recomendaciones de contenido multimedia.
Se proporcionan ejemplos de JavaScript Pixel. En el caso de BigQuery, se proporciona el esquema de tabla completo para cada tipo.
Para todos los tipos de eventos de usuario, userId es opcional.
Ten en cuenta lo siguiente:
- El campo
tagIdssolo es necesario si ejecutas un experimento de A/B. - El campo
attributionTokenes opcional. Se usa para medir el rendimiento. Los eventossearchyview-itemque se generan a partir de los clics en las recomendaciones de contenido multimedia deben tener un token de atribución para vincular los eventos con las recomendaciones que los generaron.
Para obtener más detalles sobre el objeto de evento de usuario, consulta la documentación de referencia de la API de UserEvent.
view-category-page
A continuación, se muestra el formato del evento de usuario view-category-page.
Objeto view-category-page mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario view-category-page.
Si bien, por lo general, solo hay una categoría asociada a una página, el campo pageCategories también admite una jerarquía de categorías, que puedes proporcionar como una 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 es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.
Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para los campos opcionales se configuran en NULLABLE.
Ten en cuenta que se requiere eventTime para importar eventos con BigQuery. eventTime es una cadena con un formato de marca de tiempo.
[ { "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
A continuación, se muestra el formato de datos del evento de usuario view-item.
Objeto view-item mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario view-item.
En la mayoría de los casos, documents contiene detalles del documento asociado.
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 es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.
Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para los campos opcionales se configuran en NULLABLE.
Ten en cuenta que se requiere eventTime para importar eventos con BigQuery. eventTime es una cadena con un formato de marca de tiempo.
[ { "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
A continuación, se muestra el formato del evento de usuario view-home-page.
Objeto view-home-page mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario 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 es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.
Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para los campos opcionales se configuran en NULLABLE.
Ten en cuenta que se requiere eventTime para importar eventos con BigQuery. eventTime es una cadena con un formato de marca de tiempo.
[ { "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
A continuación, se muestra el formato del evento de usuario search.
Objeto search mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario search.
Se requiere al menos uno de los campos searchQuery o pageCategory:
Proporciona
searchQuerypara los eventos de búsqueda en los que el usuario ingresó una consulta de texto.Proporciona
pageCategorycuando el usuario navegó a elementos de interés mediante la navegación, es decir, haciendo clic en categorías en lugar de ingresar una búsqueda de texto.
documents debe incluir la lista de IDs de documentos que se muestra al usuario final en la página de resultados de la búsqueda.
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 es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.
Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para los campos opcionales se configuran en NULLABLE.
Ten en cuenta que se requiere eventTime para importar eventos con BigQuery. eventTime es una cadena con un formato de marca de tiempo.
[ { "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
A continuación, se muestra el formato del evento de usuario media-play.
Objeto media-play mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario 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 es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.
Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para los campos opcionales se configuran en NULLABLE.
Ten en cuenta que se requiere eventTime para importar eventos con BigQuery. eventTime es una cadena con un formato de marca de tiempo.
[ { "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
A continuación, se muestra el formato del evento de usuario media-complete.
Objeto media-complete mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario 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 es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.
Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para los campos opcionales se configuran en NULLABLE.
Ten en cuenta que se requiere eventTime para importar eventos con BigQuery. eventTime es una cadena con un formato de marca de tiempo.
[ { "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
Puedes incluir atributos y funciones personalizados adicionales para eventos de usuario. Esto puede generar recomendaciones mejoradas y más específicas para tus usuarios cuando uses recomendaciones de contenido multimedia. Para agregar atributos personalizados, usa attributes cuando registres un evento del usuario.
Si proporcionas atributos personalizados para los eventos del usuario transferidos, es importante que también los incluyas en los eventos del usuario que asocies con las solicitudes de recomendación. El formato de los atributos personalizados debe ser coherente entre los eventos importados y los eventos proporcionados con las solicitudes de recomendación. Esto permite que las apps de recomendaciones de contenido multimedia usen esos atributos personalizados para mejorar la calidad.
Puedes proporcionar valores de texto personalizados con el campo text o valores numéricos personalizados con el campo numbers.
Por ejemplo, a continuación se muestra la sección attributes de una solicitud para registrar un evento del usuario:
attributes: { user_age: {text: ["teen", "young adult"]}, user_location: {text: ["CA"]}, user_zip: {numbers: [90210]} }
Acerca de la información del usuario
userPseudoId representa el identificador de usuario único y es obligatorio cuando registras un evento del usuario.
La información del usuario (UserInfo) incluida cuando registras un evento del usuario contiene el valor userPseudoId y, si está disponible, el valor userId.
userId es opcional y se puede usar como un identificador único y persistente para un usuario en todos los dispositivos cada vez que este acceda a tu sitio. Cuando registras userId para un usuario, las apps de recomendaciones de contenido multimedia pueden generar resultados más personalizados para un usuario en varios dispositivos, como un dispositivo móvil y un navegador web.
Acerca de la marca de tiempo
Cuando registres un evento del usuario, asegúrate de incluir una marca de tiempo precisa de cuándo ocurrió el evento. Las marcas de tiempo precisas garantizan que tus eventos se almacenen en el orden correcto. Las marcas de tiempo se registran automáticamente para los eventos recopilados con el píxel de JavaScript. Cuando importes eventos, debes proporcionar la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.
¿Qué sigue?
- Aprende a registrar eventos de usuario.