Eventos del usuario

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

add-to-cart

detail-page-view

purchase-complete

home-page-view (para Recomendaciones IA)

search (para Retail Search)
Importante para mejorar la calidad del modelo de Recomendaciones IA a lo largo del tiempo

category-page-view

search

shopping-cart-page-view

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:

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 Product.name es obligatorio para todos los productos. Usa el nombre completo de recurso del producto, en lugar del ID del producto, que es el componente final del nombre del recurso.

La API de Retail no puede usar un evento que incluya un producto sin el campo Product.name.

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 purchase_transaction.revenue.

Sin este campo, los modelos de optimización de ingresos no estarán disponibles.

Incluye exactamente un purchase_transaction.currency_code en todos los eventos de compra.

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

search_query debe existir para los eventos de búsqueda (excepto para los eventos de navegación).

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, filter debe existir y analizar correctamente.

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 attribution_token para vincular otros eventos a los de búsqueda.

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:

  • search
  • detail-page-view
  • add-to-cart
  • purchase-complete

 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:
  • Los eventos search contienen la lista de productos en el orden en que se muestra al usuario final.
  • Al menos 7 días de eventos de usuario para los tipos de eventos de usuario de la lista.
 7 días
Tasa de clics
  • search
  • detail-page-view
  • add-to-cart (opcional, pero altamente recomendado)
 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
  • search
  • detail-page-view
  • add-to-cart
  • purchase-complete
 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 eventos predict, search y detail-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"
 }
]
}
]

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?