En esta página, se describe el objeto de eventos del usuario, incluida la enumeración de posibles tipos de eventos del usuario, y se proporcionan datos de muestra para todos ellos.
La venta minorista usa eventos de usuario en tiempo real para generar recomendaciones y resultados de la búsqueda. Cuando subes datos a la API de Retail, Recomendaciones IA y Retail Search pueden usar esos datos, por lo que no necesitas subir los mismos eventos dos veces si usas ambos servicios.
Para obtener ayuda con el resgistro de eventos del usuario, consulta Registra eventos de usuarios en tiempo real.
Tipos de eventos del usuario
Existen varios tipos de eventos de usuarios que puedes registrar a medida que los usuarios exploran tu sitio de venta minorista:
Nombre del evento del usuario | Acción del usuario |
---|---|
add-to-cart | Agrega el producto al carrito. |
category-page-view | Visualiza páginas especiales, como páginas de ofertas o de promociones. |
detail-page-view | Visualiza la página de detalles del producto. |
home-page-view | Visualiza la página principal. |
purchase-complete | Completa la confirmación de la compra. |
búsqueda | Busca en el catálogo. |
shopping-cart-page-view | Visualiza el carrito de compras. |
Para obtener información detallada sobre el objeto UserEvent, consulta UserEvent.
Prioridad del tipo de evento
Si quieres obtener resultados de la mayor calidad, te recomendamos que registres los eventos de usuario para todos los tipos de eventos. En la siguiente tabla, se describe la prioridad de los diferentes tipos de eventos del usuario. Debes registrar los eventos de usuario con mayor prioridad para lograr modelos de datos de calidad.
Prioridad | Eventos del usuario |
---|---|
Obligatorio para el experimento inicial en vivo |
|
Importante para mejorar la calidad del modelo de Recomendaciones IA a lo largo del tiempo |
Requisitos y prácticas recomendadas para eventos del usuario
En las siguientes tablas, se enumeran los requisitos y las prácticas recomendadas para los tipos de eventos del usuario que Recomendaciones IA y Retail Search usan. Verifica que tus eventos de usuario cumplan con estos requisitos para que la API de Retail pueda generar resultados de calidad.
En esta sección, se enumera lo siguiente:
- Requisitos de la API de Retail: Requisitos generales de los eventos del usuario para la API de Retail. Estos requisitos se aplican si usas Recomendaciones IA y Retail Search.
- Requisitos específicos de Recomendaciones IA: Requisitos de los eventos de usuario para Recomendaciones IA.
- Requisitos específicos de Retail Search: Requisitos de los eventos de usuario para Retail Search.
Si usas modelos de Recomendaciones IA, también consulta los requisitos de los datos de eventos de usuario, en los que se enumeran requisitos adicionales según el tipo de modelo de recomendación y el objetivo de optimización que planeas usar.
Requisitos de la API de Retail
Asegúrate de que tus eventos de usuario cumplan con los siguientes requisitos para que la API de Retail pueda generar resultados de calidad. Estos se aplican tanto a Recomendaciones IA como a Retail Search.
Tipo de evento | Requisito | Impacto |
---|---|---|
Todos los eventos |
No incluyas eventos duplicados. |
Los eventos duplicados pueden causar valores de métricas incorrectos y afectar de forma negativa la calidad del modelo. |
Incluye al menos 100 ID de visitantes únicos para cada tipo de evento transferido. |
Esto garantiza que la API de Retail tenga suficientes datos para generar resultados de calidad. |
|
El campo |
La API de Retail no puede usar un evento que incluya un producto sin el campo |
|
Los productos incluidos en los eventos deben existir en tu catálogo de productos. |
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 las recomendaciones o los resultados de la búsqueda. |
|
detail-page-view |
Incluye exactamente un producto por evento. |
No se puede usar el evento si no existe ningún producto. Si se incluyen varios productos, el evento tiene un formato incorrecto y no se puede usar. |
add-to-cart |
Incluye exactamente un producto por evento. |
Si se incluyen varios productos, el evento tiene un formato incorrecto y no se puede usar. |
purchase-complete |
Incluye |
Sin este campo, los modelos de optimización de ingresos no estarán disponibles. |
Incluye exactamente un |
Los eventos de compra sin este campo dan como resultado métricas de ingresos incorrectas. |
Requisitos específicos de Recomendaciones IA
Si usas Recomendaciones IA, asegúrate de que tus eventos de usuario cumplan con los siguientes requisitos.
Si usas modelos de Recomendaciones IA, también consulta los requisitos de los datos de eventos de usuario, en los que se enumeran requisitos adicionales según el tipo de modelo de recomendación y el objetivo de optimización que planeas usar.
Tipo de evento | Requisito | Impacto |
---|---|---|
purchase |
No compactes las cestas de varios artículos en varios eventos de compra. Deberían permanecer como eventos únicos de compra que incluyan varios productos. |
Esto garantiza que se generen patrones de compra en conjunto válidos. |
Requisitos específicos de Retail Search
Si usas Retail Search, asegúrate de que los eventos de usuario cumplan con los siguientes requisitos.
Tipo de evento | Requisito | Impacto |
---|---|---|
search |
|
No incluir este campo puede tener un impacto negativo grave en la calidad del resultado de la búsqueda y las métricas. |
El ID de visitante en las solicitudes de búsqueda debe coincidir con el ID de visitante enviado en eventos relacionados con esa solicitud de búsqueda. |
Si no coinciden, los eventos tienen un formato incorrecto y las métricas pueden ser incorrectas. |
|
La lista de ID de productos en los eventos de búsqueda debe coincidir con la lista de productos que se muestra al usuario en su totalidad. |
Si no coinciden, el impacto negativo en la calidad de los resultados de la búsqueda puede ser grave y las métricas serán incorrectas. |
|
Si la búsqueda usa un filtro, |
Si este campo no existe, la API de Retail no puede usar la parte del filtro de los datos, lo que puede tener un impacto negativo en la calidad de los resultados de la búsqueda. |
|
Incluye el campo |
No incluir un token de búsqueda tiene un impacto negativo grave en la calidad de la búsqueda y la exactitud de las métricas. |
Requisitos del objetivo de búsqueda
Los diferentes objetivos de optimización tienen distintos requisitos de datos y de volúmenes de datos.
Confirma que puedes cumplir con los requisitos mínimos de datos para tu objetivo y trabaja con el equipo de ingeniería de Retail Search para elegir un objetivo de optimización específico.
El período de recopilación de datos representa la cantidad de tiempo máxima que la API de Retail revisa los eventos del usuario.
Objetivo de optimización | Tipos de eventos del usuario | Requisito mínimo de datos | Período de recopilación de datos |
---|---|---|---|
Relevancia |
Opcional, pero altamente recomendado:
|
No hay requisitos explícitos de datos mínimos para este objetivo. Retail Search puede proporcionar buenos resultados sin eventos de usuario preexistentes. Sin embargo, se recomienda cumplir con los siguientes lineamientos para mejorar la relevancia de los resultados:
|
7 días |
Tasa de clics |
|
Al menos 21 días de eventos de usuario de los tipos requeridos O (2,000,000 de eventos search Y 500,000 eventos detail-page-view generados a partir de clics de búsqueda Y 100 productos únicos de los clics de búsqueda Y un promedio de al menos 10 clics en la búsqueda por producto que se puede buscar). |
3 semanas o hasta que se cumpla el requisito mínimo de datos |
Porcentaje de conversiones/Ingresos |
|
Los eventos search contienen la lista de productos en el orden en que se muestra al usuario final Y (al menos 28 días de eventos de usuario del tipo requerido O [4,000,000 de eventos search Y 1,000,000 de eventos detail-page-view generados a partir de clics de búsqueda Y un promedio de al menos 0.5 de eventos purchase-complete por producto que se puede buscar que se generan a partir de actividades de búsqueda]). |
1 mes o hasta que se cumpla el requisito mínimo de datos |
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 admite la API de Retail.
Se proporcionan ejemplos de JavaScript Pixel y Tag Manager. 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. Los campos de información del producto (priceInfo
y availability
) son opcionales.
Ten en cuenta lo siguiente:
- El campo
experimentIds
solo es necesario si ejecutas un experimento de A/B. - El campo
attributionToken
es opcional. Se usa para medir el rendimiento. Los eventospredict
,search
ydetail-page-view
que se generan a partir de los clics de la API de Retail deben tener un token de atribución para vincular los eventos con las búsquedas o recomendaciones que los generaron. - Asegúrate de que todos tus eventos usen una moneda única, en especial si planeas usar Cloud Console para obtener métricas de ingresos. La API de Retail no admite el uso de varias monedas por catálogo.
Para obtener más detalles sobre el objeto de evento de usuario, consulta Eventos de usuario.
Agregar al carrito de compra
A continuación, se muestra el formato del evento de usuario add-to-cart
.
Objeto add-to-cart mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario add-to-cart
.
JavaScript Pixel
var user_event = { "eventType": "add-to-cart", "visitorId": "visitor-id", "cartId": "cart-id", "productDetails": [{ "product": { "id": "product-id" }, "quantity": product-quantity }] };
Tag Manager
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'add-to-cart', 'visitorId': 'visitor-id', // You can also define the visitor ID // directly on the Tag Manager tag. 'cartId': 'cart-id', 'productDetails': [{ 'product': { 'id': 'product-id' }, 'quantity': product-quantity }] } }); </script>
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 string con un formato de marca de tiempo.
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
},
{
"name": "quantity",
"type": "INTEGER",
"mode": "REQUIRED"
}
]
}
]
Vista de página de categoría
A continuación, se muestra el formato del evento de usuario category-page-view
.
Objeto category-page-view mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario category-page-view
.
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": "category-page-view", "visitorId": "visitor-id", "pageCategories": ["category1 > category2"] };
Tag Manager
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'category-page-view', 'visitorId": 'visitor-id', // You can also define the user ID and visitor ID // directly on the Tag Manager tag. 'pageCategories': ['category1 > category2'] } }); </script>
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 string con un formato de marca de tiempo.
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
}
]
Vista de página de detalles
A continuación, se muestra el formato de datos del evento de usuario detail-page-view
.
Objeto detail-page-view mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario detail-page-view
.
En la mayoría de los casos, productDetails
contiene detalles del producto asociado, a menos que un paquete de artículos se venda de forma conjunta.
JavaScript Pixel
var user_event = { "eventType": "detail-page-view", "visitorId": "visitor-id", "productDetails": [{ "product": { "id": "product-id" } }] };
Tag Manager
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'detail-page-view', 'visitorId': 'visitor-id', // You can also define the visitor ID directly on // the Tag Manager tag. 'productDetails': [{ 'product': { 'id': 'product-id' } }] } }); </script>
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 string con un formato de marca de tiempo.
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
}
]
}
]
Vista de página principal
A continuación, se muestra el formato del evento de usuario home-page-view
.
Objeto home-page-view mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario home-page-view
.
JavaScript Pixel
var user_event = { "eventType": "home-page-view", "visitorId": "visitor-id", };
Tag Manager
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'home-page-view', 'visitorId': 'visitor-id' // You can also define the visitor ID // directly on the Tag Manager tag. } }); </script>
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 string con un formato de marca de tiempo.
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
}
]
Se realizó la compra
A continuación, se muestra el formato de datos del evento de usuario purchase-complete
.
Objeto purchase-complete mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario purchase-complete
.
JavaScript Pixel
var user_event = { "eventType": "purchase-complete", "visitorId": "visitor-id", "productDetails": [{ "product": { "id": "product-id" }, "quantity": product-quantity }], "purchaseTransaction": { "revenue": revenue, "currencyCode": "currency-code" } };
Tag Manager
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'purchase-complete', 'visitorId': 'visitor-id', // You can also define the visitor id directly on // the Tag Manager tag. 'productDetails': [{ 'product': { 'id': 'product-id' }, 'quantity': product-quantity }], 'purchaseTransaction': { 'revenue': revenue, 'currencyCode': 'currency-code' } } }); </script>
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 string con un formato de marca de tiempo.
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
},
{
"name": "quantity",
"type": "INTEGER",
"mode": "REQUIRED"
}
]
},
{
"name": "purchaseTransaction",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "revenue",
"type": "FLOAT",
"mode": "REQUIRED"
},
{
"name": "currencyCode",
"type": "STRING",
"mode": "REQUIRED"
}
]
}
]
Buscar
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 pageCategories
.
productDetails
debe incluir la lista de ID de productos que se muestra al usuario final en la página de resultados de búsqueda.
JavaScript Pixel
var user_event = { "eventType": "search", "visitorId": "visitor-id", "searchQuery": "search-query", "pageCategories": ["category1 > category2"], "productDetails": [ { "product": { "id": "product-id1" } }, { "product": { "id": "product-id2" } } ] };
Tag Manager
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'search', 'visitorId': 'visitor-id', // You can also define the visitor ID // directly on the Tag Manager tag. 'searchQuery': 'search-query', 'pageCategories': ['category1 > category2'], 'productDetails': [ { 'product': { 'id': 'product-id1' } }, { 'product': { 'id': 'product-id2' } } ] } }); </script>
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 string con un formato de marca de tiempo.
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "productDetails",
"type": "RECORD",
"mode": "REPEATED",
"fields": [
{
"name": "product",
"type": "RECORD",
"mode": "REQUIRED",
"fields": [
{
"name": "id",
"type": "STRING",
"mode": "REQUIRED"
}
]
}
]
},
{
"name": "searchQuery",
"type": "STRING",
"mode": "NULLABLE"
},
{
"name": "pageCategories",
"type": "STRING",
"mode": "REPEATED"
}
]
Vista de la página del carrito de compras
A continuación, se muestra el formato de datos del evento de usuario shopping-cart-page-view
.
Objeto shopping-cart-page-view mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario shopping-cart-page-view
.
Proporciona el objeto productDetails
, a menos que el carrito de compras esté vacío.
JavaScript Pixel
var user_event = { "eventType": "shopping-cart-page-view", "visitorId": "visitor-id "cartId": "cart-id", "productDetails": [{ "product": { "id": "product-id" }, { "id": "product-id" } }] };
Tag Manager
<script> dataLayer = dataLayer || []; dataLayer.push({ 'cloud_retail': { 'eventType': 'shopping-cart-page-view', 'visitorId': 'visitor-id' // You can also define the visitor ID // directly on the Tag Manager tag. 'cartId': 'cart-id', 'productDetails': [{ 'product': { 'id': 'product-id' }, { 'id': 'product-id' } }] } }); </script>
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 string con un formato de marca de tiempo.
[
{
"name": "eventType",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "visitorId",
"type": "STRING",
"mode": "REQUIRED"
},
{
"name": "eventTime",
"type": "STRING",
"mode": "REQUIRED"
}
]
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 IA. A fin de agregar atributos personalizados, usa attributes
cuando registres un evento del usuario.
Puedes proporcionar valores de texto personalizados con el campo text
o valores numéricos personalizados con el campo number
.
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"]} ]
Acerca de la información del usuario
visitorId
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 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, la API de Retail puede 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 la API Retail almacene eventos en el orden correcto. Las marcas de tiempo se registran de forma automática para los eventos recopilados mediante Tag Manager y JavaScript Pixel. 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.