Configura los eventos de 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.

Para configurar tus eventos de usuario, sigue estos pasos:

  1. Importa eventos históricos de usuarios.

  2. Registra eventos de usuario en vivo.

  3. Etiqueta los eventos de usuario con entidades.

  4. Marca los eventos de usuario con tokens de atribución.

Vertex AI Search para venta minorista usa eventos de usuario en tiempo real para generar recomendaciones y resultados de la búsqueda. Cuando subes datos, tanto las recomendaciones como la búsqueda pueden usarlos, por lo que no es necesario subir los mismos eventos dos veces si usas ambos servicios.

Para obtener ayuda con el registro de eventos de 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)

search (para la búsqueda)
Importante para mejorar la calidad del modelo de recomendaciones 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 de usuario que usan las recomendaciones y la búsqueda. Verifica que tus eventos de usuario cumplan con estos requisitos para que Vertex AI Search for Retail pueda generar resultados de calidad.

En esta sección, se enumera lo siguiente:

Si usas modelos de recomendaciones, también consulta los requisitos de datos de tipo de modelo, 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.

Puedes ver las métricas de calidad de los datos de la búsqueda en la página Calidad de los datos de la consola de Search for Retail. Estas métricas muestran los porcentajes de productos y eventos de usuario que cumplen con los estándares de calidad de los datos recomendados. Si quieres obtener información para ver la calidad de los datos de búsqueda, consulta Desbloquea los niveles de rendimiento de la búsqueda.

Requisitos para los eventos del usuario

Asegúrate de que tus eventos de usuario cumplan con los siguientes requisitos para que Vertex AI Search for Retail pueda generar resultados de calidad. Se aplican a las recomendaciones y a la búsqueda.

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 del modelo y, a menudo, impiden que entrenamiento de modelos correctamente. Los eventos duplicados pueden causar valores de métricas incorrectos.

Incluye al menos 100 ID de visitantes únicos para cada tipo de evento transferido.

Esto garantiza que Vertex AI Search para venta minorista tenga suficientes datos para generar resultados de calidad.

Los IDs de visitante deben tener el mismo formato en la importación de eventos o su registro, y en las solicitudes a la API.

El uso de un formato coherente para los IDs de visitante ayuda a identificar correctamente los patrones de los visitantes y a proporcionar resultados de mejor calidad en función del comportamiento de los usuarios.

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.

Los datos de eventos no unidos no se usan para entrenar modelos. Sin embargo, los eventos no unidos se pueden unir más adelante, después de que se hayan transferido los productos asociados. Para obtener más información, consulta Cómo volver a unirte a eventos de usuario.

Algunos eventos de usuario deben tener el mismo ID de visitante.

Para construir historias de secuencias de comportamiento válidas, la Búsqueda de Vertex AI para venta minorista debe poder ver varios eventos con el mismo ID de visitante.

Por ejemplo, visitor123 vio cinco páginas de detalles del producto, agregó tres productos a su carrito y, luego, compró dos de los cinco productos originales. Si todos estos eventos proporcionan el mismo ID de visitante con un formato coherente, Vertex AI Search para venta minorista puede considerar esa secuencia de comportamiento en sus modelos.

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.

Los eventos purchase-complete a los que les falta el campo revenue no se usan para entrenar modelos.

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

No hay un código de moneda predeterminado; se debe proporcionar uno.

Los eventos de compra sin este campo dan como resultado métricas de ingresos incorrectas.

Verifica que algunos eventos de compra incluyan varios productos.

Tener algunos eventos de compra con varios productos ayuda al modelo a aprender patrones de compra conjunta.

Requisitos específicos de Recomendaciones

Si usas recomendaciones, asegúrate de que tus eventos de usuario cumplan con los siguientes requisitos.

Si usas modelos de recomendaciones, también consulta los requisitos de datos de tipo de modelo, 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-complete

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 de búsqueda

Si usas la búsqueda, asegúrate de que tus eventos de usuario cumplan con los siguientes requisitos mínimos para obtener resultados.

Tipo de evento Requisito Impacto
search

searchQuery debe existir para los eventos de búsqueda y pageCategories debe existir 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, Vertex AI Search for Retail no puede usar la parte del filtro de los datos, lo que puede afectar de forma negativa la calidad de los resultados de la búsqueda.

Incluye el campo attribution_token para vincular otros eventos a los de búsqueda.

Si no incluyes un token de atribución, se activará un error en la Búsqueda para comercios y se tendrá un impacto negativo grave en la calidad de la búsqueda y la exactitud de las métricas.

Requisitos de optimización de la búsqueda

Para permitir que la búsqueda optimice automáticamente la experiencia de búsqueda según las tendencias generales de los usuarios, sube los siguientes datos.

Los eventos deben subirse al menos a diario con una demora máxima de 24 horas.

Métrica de eventos Volumen o frecuencia de eventos Descripción
Volumen de eventos de search 250,000 en los últimos 90 días

Se exigen al menos 250,000 eventos en los últimos 90 días para optimizar la experiencia de búsqueda en función de los eventos transferidos.

Recomendamos subir eventos al menos una vez al día para mantener una buena calidad de los datos. Durante las importaciones de eventos históricos, asegúrate de que la distribución de datos se incline hacia la marca de tiempo más reciente. La cantidad de eventos del último día de la marca de tiempo debe ser igual o superior al recuento promedio de eventos diarios.

Volumen de detail-page-view atribuible a un evento search 500,000 en los últimos 30 días Se exigen al menos 500,000 eventos para optimizar los resultados de la búsqueda con eventos de usuario.
Cantidad promedio de eventos detail-page-view atribuibles a un evento search por producto 10 en los últimos 30 días Obligatorio para optimizar los resultados de la búsqueda con los eventos transferidos, a menos que se suban los eventos de los últimos 21 días.
Proporción de eventos search con filtros analizables 0.1 en los últimos 30 días Se recomienda para optimizar el orden de las facetas dinámicas en la respuesta de búsqueda.
Proporción de productos buscados con precio 0.95 en los últimos 30 días Obligatorio para optimizar los resultados de la búsqueda con los eventos transferidos.
Cantidad promedio de eventos add-to-cart atribuibles a un evento search por producto con precio 0.5 en los últimos 30 días Se recomienda para los resultados de la búsqueda optimizados para los ingresos.
Cantidad promedio de eventos purchase-complete atribuibles a un evento search por producto con precio que se puede buscar 0.5 en los últimos 30 días Se recomienda para los resultados de la búsqueda optimizados para los ingresos.

Requisitos de personalización de la Búsqueda

La Búsqueda requiere los siguientes datos para personalizar la búsqueda de texto y explorar los resultados de la búsqueda de tus usuarios en función de su actividad.

Después de subir los siguientes datos, la búsqueda puede personalizar los resultados automáticamente.

Métrica de eventos Volumen o frecuencia de eventos Descripción
Volumen de eventos de search que entrega la búsqueda 100,000 en los últimos 30 días

Se requieren al menos 100,000 eventos publicados por la búsqueda en los últimos 30 días para proporcionar personalización.

Los resultados de la búsqueda no se almacenan en caché Menos del 1% de los 100,000 eventos de usuario más recientes

No almacenes en caché los resultados de la búsqueda de texto ni las búsquedas de exploración si planeas usar la personalización. El uso de los mismos resultados para todos los visitantes impide que la búsqueda proporcione resultados realmente personalizados a cualquier usuario determinado y corre el riesgo de exponer los datos privados de los usuarios. La Búsqueda desactiva automáticamente la personalización si se detecta el almacenamiento en caché.

Si solo almacenas en caché los resultados de la búsqueda, la búsqueda aún puede personalizar los resultados de la navegación. Por el contrario, si solo almacenas en caché los resultados de la navegación, la Búsqueda aún puede personalizar los resultados de la búsqueda de consultas de texto.

Coincidencia de ID de visitante entre SearchRequests y los eventos del usuario Más del 10% de coincidencias para los 100,000 eventos de usuario más recientes Asegúrate de que el espaciado y el formato del ID de visitante coincidan en SearchRequests y los eventos del usuario. El formato coherente del ID de visitante garantiza que la búsqueda pueda identificar la actividad del usuario correctamente.

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 admitido.

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 obligatorio solo para Vertex AI Search para la venta minorista. Se usa para medir el rendimiento. Los eventos predict, search y detail-page-view que se generan a partir de clics deben tener un token de atribución para vincular los eventos a las búsquedas o recomendaciones que los generaron.
  • Asegúrate de que todos tus eventos usen una moneda única, en especial si planeas usar la consola de Google Cloud para obtener métricas de ingresos. La API de Vertex AI Search for Retail no admite el uso de varias monedas por catálogo.

Para obtener más detalles sobre el objeto de evento de usuario, consulta la documentación de referencia de la API de UserEvent.

Agregar al carrito

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.

Cuando importes eventos, debes proporcionar la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.

Es posible que se requieran otros campos según el método de la API que se use o si se usan campos adicionales. (por ejemplo, si el evento del usuario está asociado con una entidad, asegúrate de especificar el campo entity). Para obtener detalles completos de cada campo y cuándo son obligatorios, consulta la documentación de referencia de la API de UserEvent.

JavaScript Pixel

var user_event = {
  "eventType": "add-to-cart",
  "visitorId": "visitor-id",
  "productDetails": [{
    "product": {
      "id": "product-id"
    },
    "quantity": { "value": 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.
        '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": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "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": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

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.

Cuando importes eventos, debes proporcionar la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.

Es posible que se requieran otros campos según el método de la API que se use o si se usan campos adicionales. (por ejemplo, si el evento del usuario está asociado con una entidad, asegúrate de especificar el campo entity). Para obtener detalles completos de cada campo y cuándo son obligatorios, consulta la documentación de referencia de la API de UserEvent.

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": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "pageCategories",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

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.

Cuando importes eventos, debes proporcionar la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.

Es posible que se requieran otros campos según el método de la API que se use o si se usan campos adicionales. (por ejemplo, si el evento del usuario está asociado con una entidad, asegúrate de especificar el campo entity). Para obtener detalles completos de cada campo y cuándo son obligatorios, consulta la documentación de referencia de la API de UserEvent.

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": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         }
       ]
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

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.

Cuando importes eventos, debes proporcionar la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.

Es posible que se requieran otros campos según el método de la API que se use o si se usan campos adicionales. (por ejemplo, si el evento del usuario está asociado con una entidad, asegúrate de especificar el campo entity). Para obtener detalles completos de cada campo y cuándo son obligatorios, consulta la documentación de referencia de la API de UserEvent.

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"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "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": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

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.

Cuando importes eventos, debes proporcionar la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.

Es posible que se requieran otros campos según el método de la API que se use o si se usan campos adicionales. (por ejemplo, si el evento del usuario está asociado con una entidad, asegúrate de especificar el campo entity). Para obtener detalles completos de cada campo y cuándo son obligatorios, consulta la documentación de referencia de la API de UserEvent.

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": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "productDetails",
   "type": "RECORD",
   "mode": "REPEATED",
   "fields": [
     {
       "name": "product",
       "type": "RECORD",
       "mode": "REQUIRED",
       "fields": [
         {
           "name": "id",
           "type": "STRING",
           "mode": "REQUIRED"
         },
         {
           "name": "priceInfo",
           "type": "RECORD",
           "mode": "NULLABLE",
           "fields": [
             {
               "name": "price",
               "type": "FLOAT",
               "mode": "REQUIRED"
             },
             {
               "name": "originalPrice",
               "type": "FLOAT",
               "mode": "NULLABLE"
             },
             {
               "name": "currencyCode",
               "type": "STRING",
               "mode": "REQUIRED"
             },
             {
               "name": "cost",
               "type": "FLOAT",
               "mode": "NULLABLE"
             }
           ]
         }
       ]
     },
     {
       "name": "quantity",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "purchaseTransaction",
   "type": "RECORD",
   "mode": "REQUIRED",
   "fields": [
     {
       "name": "id",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "revenue",
       "type": "FLOAT",
       "mode": "REQUIRED"
     },
     {
       "name": "tax",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "cost",
       "type": "FLOAT",
       "mode": "NULLABLE"
     },
     {
       "name": "currencyCode",
       "type": "STRING",
       "mode": "REQUIRED"
     }
   ]
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

A continuación, se muestra el formato del evento de usuario search.

Objeto search mínimo requerido

Estos son los campos mínimos obligatorios para que funcione Vertex AI Search for Retail:

  • Para mostrar una lista de resultados de la búsqueda, Vertex AI Search para la venta minorista requiere searchQuery y productDetails:

    • searchQuery se lee del parámetro search_term o de los eventos view_search_results.
    • productDetails se lee del parámetro items del evento view_item_list. Debe incluir la lista de IDs de productos que se muestra al usuario final en la página de resultados de la búsqueda.

  • Se requiere al menos uno de los campos searchQuery o pageCategories.

En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario search.

Cuando importes eventos, debes proporcionar la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.

Es posible que se requieran otros campos según el método de la API que se use o si se usan campos adicionales. (por ejemplo, si el evento del usuario está asociado con una entidad, asegúrate de especificar el campo entity). Para obtener detalles completos de cada campo y cuándo son obligatorios, consulta la documentación de referencia de la API de UserEvent.

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"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Autocompletar

Este campo solo es obligatorio para los eventos de búsqueda si deseas usar la función Autocomplete. No es obligatorio para la búsqueda.

En los siguientes ejemplos, se muestra el campo completionDetail cuando un usuario escribe "sh" y hace clic en la segunda sugerencia, "zapatos", en la lista de sugerencias para activar un evento de búsqueda. Si el usuario no hace clic en ninguna sugerencia, el campo completionDetail permanecerá vacío.

eventType debe ser "search"

completionAttributionToken es el attributionToken de la respuesta de completeQuery.

selectedSuggestion debe ser igual a searchQuery.

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"
      }
    }
  ]
  "completionDetail": {
    "completionAttributionToken": "completion_token",
    "selectedSuggestion": "search-query",
    "selectedPosition": completion_position
  }
};

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'
            }
          }
        ]
        "completionDetail": {
          "completionAttributionToken": 'completion_token',
          "selectedSuggestion": 'search-query',
          "selectedPosition": completion_position
        }
      }
    });
</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"
 },
 {
   "name": "completionDetail",
   "type": "RECORD"
   "mode": "NULLABLE"
   "fields": [
     {
       "name": "completionAttributionToken",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedSuggestion",
       "type": "STRING",
       "mode": "REQUIRED"
     },
     {
       "name": "selectedPosition",
       "type": "INTEGER",
       "mode": "REQUIRED"
     }
    ]
 }
]

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.

Cuando importes eventos, debes proporcionar la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.

Es posible que se requieran otros campos según el método de la API que se use o si se usan campos adicionales. (por ejemplo, si el evento del usuario está asociado con una entidad, asegúrate de especificar el campo entity). Para obtener detalles completos de cada campo y cuándo son obligatorios, consulta la documentación de referencia de la API de UserEvent.

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"
 },
 {
   "name": "experimentIds",
   "type": "STRING",
   "mode": "REPEATED"
 },
 {
   "name": "attributionToken",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "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": "cartId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "userInfo",
   "type": "RECORD",
   "mode": "NULLABLE",
   "fields": [
     {
       "name": "userId",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "ipAddress",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "userAgent",
       "type": "STRING",
       "mode": "NULLABLE"
     },
     {
       "name": "directUserRequest",
       "type": "BOOLEAN",
       "mode": "NULLABLE"
     }
   ]
 },
 {
   "name": "uri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "referrerUri",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "pageViewId",
   "type": "STRING",
   "mode": "NULLABLE"
 },
 {
   "name": "entity",
   "type": "STRING",
   "mode": "NULLABLE"
 }
]

Campos de eventos del usuario de Google Analytics 4

En la siguiente tabla, se muestra cómo se asignan los campos de eventos del usuario de Google Analytics 4 a Vertex AI Search para los campos de venta minorista.

Antes de importar o registrar eventos de usuarios de Google Analytics 4, asegúrate de que tus eventos de usuarios de Google Analytics 4 usen los siguientes campos para que Vertex AI Search for retail pueda integrar tus datos correctamente.

Google Analytics 4 Venta minorista
ecommerce.purchase_revenue purchaseTransaction.revenue
event_name eventType
event_timestamp eventTime
items.item_id productDetails.product.id
items.price productDetails.product.priceInfo.price
items.quantity productDetails.quantity
Clave:
event_params.key establecida en "currency"

Valor:
event_params.value.string_value		 productDetails.product.priceInfo.currencyCode
Clave:
event_params.key establecida en "currency"

Valor:
event_params.value.string_value		 purchaseTransaction.currencyCode
Clave:
event_params.key establecida en "search_term"

Valor:
event_params.value.string_value		 searchQuery
user_id userInfo.userId
user_pseudo_id visitorId

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. 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 predicción. El formato de los atributos personalizados debe ser coherente entre los eventos importados y los eventos proporcionados con solicitudes de predicción. Esto permite el uso de esos atributos personalizados cuando se entrenan modelos y se publican predicciones, lo que ayuda a mejorar la calidad de las recomendaciones.

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 visitorId 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, Vertex AI Search para venta minorista 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 los eventos se almacenen en el orden correcto. Las marcas de tiempo se registran automáticamente 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?