Información acerca de los 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.

Vertex AI Search for Commerce 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.

Cómo funciona la atribución de la búsqueda

Cómo funciona la atribución

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 Google Analytics 4 event_name
home-page-view Visualiza la página principal. view_homepage
search (Buscar y explorar) Busca en el catálogo. view_item_list + [searchQuery O pageCategories + filter]
category-page-view (solo para recomendaciones) Visualiza páginas especiales, como páginas de ofertas o de promociones. view_item_list + pageCategories
detail-page-view Visualiza la página de detalles del producto. view_item
add-to-cart Agrega el producto al carrito. add_to_cart
shopping-cart-page-view Visualiza el carrito de compras. begin_checkout
purchase-complete Completa la confirmación de la compra. purchase

Para obtener una lista completa de los campos de eventos de GA4, consulta Campos de eventos de usuario de Google Analytics 4.

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 Tipos de eventos del usuario

Obligatorio para la experimentación inicial en vivo de las recomendaciones

(los tipos de eventos dependen del tipo de modelo de recomendación)

detail-page-view

add-to-cart

purchase-complete

home-page-view
Se requiere un evento adicional para el experimento de búsqueda en vivo

search

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 Commerce 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 del 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 commerce. Estas métricas muestran los porcentajes de productos y eventos de usuario que cumplen con los estándares recomendados de calidad de los datos. Para obtener información sobre cómo ver la calidad de los datos de la búsqueda, consulta Desbloquea los niveles de rendimiento de la búsqueda.

Requisitos generales de los eventos de usuario

Asegúrate de que tus eventos de usuario cumplan con los siguientes requisitos para que Vertex AI Search para comercio pueda generar resultados de calidad. Se aplican tanto a las recomendaciones como 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 el entrenamiento de modelos se realice 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 verifica que Vertex AI Search para el comercio tenga suficientes datos para generar resultados de calidad.

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

Usar un formato coherente para los IDs de visitantes ayuda a identificar correctamente los patrones de los visitantes y a proporcionar resultados de mejor calidad basados en el comportamiento del usuario.

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 unirse a eventos de usuario.

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

Para crear historiales de secuencias de comportamiento válidos, Vertex AI Search for Commerce 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 comercio puede tener en cuenta 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 que no incluyen 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 del 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 verifica que se generen patrones de compra en conjunto válidos.

Requisitos específicos de la 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 Commerce 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.

No incluir un token de atribución activará un error en la Búsqueda para comercio y 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 en función de las tendencias generales de los usuarios, sube los siguientes datos.

Los eventos se deben subir al menos una vez al día 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 requieren 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 de search 500,000 en los últimos 30 días Se requieren al menos 500,000 eventos para optimizar los resultados de la búsqueda con eventos de usuario.
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 incorporados, a menos que se suban eventos de los últimos 21 días.
Proporción de eventos de 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 que se transfieren.
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.
Promedio de eventos purchase-complete atribuibles a un evento search por producto con precio apto para búsquedas 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 los resultados de búsqueda de texto y de exploración para 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 de exploración si planeas usar la personalización. Reutilizar los mismos resultados para todos los visitantes impide que la Búsqueda proporcione resultados verdaderamente personalizados a cualquier usuario y expone los datos privados de los usuarios. La Búsqueda desactiva automáticamente la personalización si se detecta 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.

Coincidencias del 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 los eventos de usuario y SearchRequests. El formato coherente del ID de visitante verifica 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 solo es obligatorio para Vertex AI Search for Commerce. Se usa para medir el rendimiento. Los tokens de atribución no se deben enviar a predict, search ni detail-page-view, ni a los eventos de clic.
  • Asegúrate de que todos tus eventos usen una sola moneda, en especial si planeas usar la consola deGoogle Cloud para obtener métricas de ingresos. La API de Vertex AI Search for Commerce 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.

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 a una entidad, asegúrate de especificar el campo entity). Para obtener todos los detalles 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 cadena 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.

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 a una entidad, asegúrate de especificar el campo entity). Para obtener todos los detalles 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 cadena 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.

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 a una entidad, asegúrate de especificar el campo entity). Para obtener todos los detalles 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 cadena 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.

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 a una entidad, asegúrate de especificar el campo entity). Para obtener todos los detalles 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 cadena 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.

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 a una entidad, asegúrate de especificar el campo entity). Para obtener todos los detalles 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 cadena 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 Vertex AI Search for Commerce muestre una lista de resultados de la búsqueda:

  • 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 búsqueda.
  • userEvents captura toda la información de metadatos que la API de Retail necesita saber sobre cómo interactúan los usuarios finales con el sitio web del cliente.

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 a una entidad, asegúrate de especificar el campo entity). Para obtener todos los detalles 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 cadena 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 de autocompletar. No es obligatorio para la búsqueda.

En los siguientes ejemplos, se muestra el campo completionDetail cuando un usuario escribe "za" 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 permanece vacío.

eventType debe ser "search"

completionAttributionToken es el attributionToken de la respuesta 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 cadena 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.

En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario shopping-cart-page-view.

Proporciona los objetos productDetails y userEvents, 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 a una entidad, asegúrate de especificar el campo entity). Para obtener todos los detalles 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"
      },
      "quantity": PRODUCT-QUANTITY
    }]
};

Reemplaza PRODUCT-ID, PRODUCT-QUANTITY, VISOTOR-ID y CART-ID por el ID del producto, la cantidad del producto, el ID de sesión y el ID del carrito de compras.

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'
            },
            'quantity': PRODUCT-QUANTITY
          }]
      }
    });
</script>

Reemplaza PRODUCT-ID, PRODUCT-QUANTITY, VISOTOR-ID y CART-ID por el ID del producto, la cantidad del producto, el ID de sesión y el ID del carrito de compras.

BigQuery

Este es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para los campos opcionales se configuran en NULLABLE.

Ten en cuenta que se requiere eventTime para importar eventos con BigQuery. eventTime es una cadena con un formato de marca de tiempo. 

[
 {
   "name": "eventType",
   "type": "STRING",
   "mode": "REQUIRED"
 },
 {
   "name": "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 de usuario de Google Analytics 4

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

Antes de importar o registrar eventos del usuario desde Google Analytics 4, asegúrate de que tus eventos del usuario de Google Analytics 4 utilicen los siguientes campos para que Vertex AI Search para comercio 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

¿Qué sigue?