En esta página, se describen los eventos de usuario para las apps de búsqueda y recomendaciones de contenido multimedia, incluidos los tipos de eventos de usuario, los requisitos y los ejemplos para los tipos de eventos de usuario. Los eventos del usuario son obligatorios para las apps de contenido multimedia.
Para obtener información general sobre la búsqueda y las recomendaciones de contenido multimedia, consulta Introducción a la búsqueda y las recomendaciones de contenido multimedia.
Para obtener ayuda con el registro de eventos de usuario, consulta Registra eventos de usuario en tiempo real. Para importar eventos de usuarios anteriores de forma masiva, consulta Importa eventos históricos de usuarios.
Tipos de eventos del usuario
Puedes registrar los siguientes tipos de eventos de usuario a medida que los usuarios finales navegan o buscan en tu sitio:
| Nombre del evento del usuario | Acción del usuario |
|---|---|
view-category-page |
Visualiza una página de categoría, como Principal > TV > Dramas o Principal > Películas > Acción. |
view-item |
Ve los detalles de un documento. |
view-home-page |
Visualiza la página principal. |
search |
Busca en el almacén de datos. |
media-play |
Los clics se reproducen en un elemento multimedia. |
media-complete |
Detiene la reproducción de un elemento multimedia, lo que indica el final de la visualización. |
Para obtener detalles sobre el objeto de evento de usuario, consulta la documentación de referencia de la API de UserEvent.
Requisitos de eventos para la búsqueda y las recomendaciones de contenido multimedia
Para determinar qué eventos del usuario debes recopilar, consulta la siguiente tabla.
Los tipos de eventos de usuario que necesitas se determinan según si tu aplicación es de búsqueda o de recomendaciones, según el objetivo (porcentaje de clics, porcentaje de conversiones o duración de la visualización) y, solo para las aplicaciones de recomendaciones, según el tipo de modelo que elegiste. Para obtener más información sobre los tipos de modelos de recomendación y los objetivos de optimización, consulta Acerca de los tipos de recomendaciones de apps de medios.
| Evento | search |
view-home-page |
view-category-page |
view-item |
media-play |
media-complete |
|
|---|---|---|---|---|---|---|---|
| Caso de uso de la búsqueda | |||||||
| Obligatorio | No obligatorio |
No obligatorio |
Obligatorio | Obligatorio | Obligatorio | ||
| Tipo de modelo Recomendado para ti, por objetivo | |||||||
| CTR | No obligatorio |
Se requiere para el contexto de la página principal No se requiere para el contexto general |
No obligatorio |
Se requiere view-item o media-play. |
Altamente recomendado Obligatorio si la reducción de la clasificación del historial está activada |
||
| CVR | No obligatorio |
Se requiere para el contexto de la página principal No se requiere para el contexto general |
No obligatorio |
Se requiere view-item o media-play. |
Obligatorio | ||
| Duración de reproducción | No obligatorio |
Se requiere para el contexto de la página principal No se requiere para el contexto general |
No obligatorio |
Se requiere view-item o media-play. |
Obligatorio | ||
| Tipo de modelo Otros elementos que podrían gustarte, por objetivo | |||||||
| CTR | No obligatorio |
No obligatorio |
No obligatorio |
Se requiere view-item o media-play. |
Se recomienda altamente Obligatorio si la reducción del historial está activada |
||
| CVR | No obligatorio |
No obligatorio |
No obligatorio |
Se requiere view-item o media-play. |
Obligatorio | ||
| Duración de reproducción | No obligatorio |
No obligatorio |
No obligatorio |
Se requiere view-item o media-play. |
Obligatorio | ||
| Tipo de modelo Más parecidas, por objetivo | |||||||
| CTR | No obligatorio |
No obligatorio |
No obligatorio |
Se requiere view-item o media-play. |
Obligatorio si la reducción de la clasificación del historial está activada | ||
| CVR | No obligatorio |
No obligatorio |
No obligatorio |
Se requiere view-item o media-play. |
Obligatorio | ||
| Duración de reproducción | No obligatorio |
No obligatorio |
No obligatorio |
Se requiere view-item o media-play. |
Obligatorio | ||
| Tipo de modelo más popular, por objetivo | |||||||
| CTR | No obligatorio |
No obligatorio |
No obligatorio |
Se requiere view-item o media-play. |
No obligatorio |
||
| CVR | No obligatorio |
No obligatorio |
No obligatorio |
No obligatorio |
No obligatorio |
Obligatorio | |
Requisitos para los eventos de usuario de medios
Asegúrate de que tus eventos de usuario cumplan con los siguientes requisitos para que tus apps de medios puedan generar resultados de calidad.
| Tipo de evento | Requisito | Impacto |
|---|---|---|
| Todos los eventos |
No incluyas datos sintéticos ni eventos duplicados. |
Los eventos sintéticos o duplicados afectan de forma negativa la calidad de los resultados y pueden impedir que implementes tu app. Los eventos duplicados pueden generar valores de métricas incorrectos. |
|
Incluye al menos 100 seudo IDs de usuarios únicos para cada tipo de evento transferido. |
Hazlo para que las apps de recomendaciones de contenido multimedia tengan suficientes datos para generar resultados de calidad. |
|
|
Los IDs de seudónimo del usuario deben tener exactamente el mismo formato en la importación o el registro de eventos, y en las solicitudes de recomendaciones de medios. |
Usar un formato coherente para los IDs de seudónimo 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 basados en el comportamiento del usuario. |
|
|
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 del usuario deben tener el mismo seudo-ID del usuario. |
Para crear historiales de secuencias de comportamiento válidos, las apps de recomendaciones de contenido multimedia deben poder ver varios eventos con el mismo ID de seudónimo 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. |
search |
Incluye |
El |
media-play |
Incluye exactamente un documento por evento. |
Si se incluyen varios documentos, el evento tiene un formato incorrecto y no se puede usar. |
Etiquetas de eventos del usuario para pruebas A/B
Si realizas pruebas A/B, asegúrate de agregar IDs de etiquetas a todos los eventos del usuario que recopiles y agrega una etiqueta para cada grupo de prueba.
Por ejemplo, agrega la etiqueta "tagIds": ["original"] a los eventos del usuario de tu modelo actual y la etiqueta "tagIds": ["google"] a los eventos del usuario de Vertex AI Search para medios.
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 medios. 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.
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.
searchQuery para los eventos de búsqueda en los que el usuario ingresó una búsqueda de texto.
El attributionToken se devuelve con los resultados de la búsqueda.
documents debe incluir la lista de IDs de documentos que se muestra al usuario final en la página de resultados de búsqueda.
JavaScript Pixel
var user_event = { eventType: "search", userPseudoId: "user-pseudo-id", eventTime: "2020-01-01T03:33:33.000001Z", searchInfo: { searchQuery: "search-query", }, attributionToken: "attribution-token", 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": "attributionToken", "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": 0.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 resultados mejorados y más específicos para tus usuarios.
Para agregar atributos personalizados, usa attributes cuando registres un evento del usuario.
Si proporcionas atributos personalizados para los eventos de usuario transferidos, es importante que también los incluyas en los eventos de usuario que asocies con las solicitudes de búsqueda y recomendación. El formato de los atributos personalizados debe ser coherente entre los eventos importados y los eventos proporcionados con las solicitudes. Esto permite que las apps de medios 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 el userId de un usuario, las apps de búsqueda y 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.