Acerca de los eventos de usuario

En esta página se describe el objeto de evento de usuario, se enumeran los posibles tipos de eventos de usuario y se proporcionan datos de ejemplo de todos los tipos de eventos de usuario.

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

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

Cómo funciona la atribución

Tipos de eventos de usuario

Hay varios tipos de eventos de usuario que puede registrar mientras los usuarios navegan por su sitio de comercio:

Nombre del evento de usuario Acción de usuario Google Analytics 4 event_name
home-page-view Muestra la página principal. view_homepage
search (Buscar y descubrir) Busca en el catálogo. view_item_list + [searchQuery O pageCategories + filter]
category-page-view (solo recomendaciones) Ve páginas especiales, como páginas de rebajas o promociones. view_item_list + pageCategories
detail-page-view Ve la página de detalles del producto. view_item
add-to-cart Añade el producto al carrito. add_to_cart
shopping-cart-page-view Ve el carrito de la compra. begin_checkout
purchase-complete Completa el proceso de compra. purchase

Para ver una lista completa de los campos de eventos de usuario de GA4, consulte 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

Para obtener resultados de la máxima calidad, te recomendamos que registres eventos de usuario de todos los tipos de eventos. En la siguiente tabla se describe la prioridad de los diferentes tipos de eventos de usuario. Debe registrar los eventos de usuario de mayor prioridad para conseguir modelos de datos de calidad.

Prioridad Tipos de eventos de usuario

Obligatorio para la experimentación inicial en tiempo real 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 directo

search

Requisitos y prácticas recomendadas para eventos de usuario

En las siguientes tablas se indican los requisitos y las prácticas recomendadas para los tipos de eventos de usuario que usan las recomendaciones y la búsqueda. Comprueba que tus eventos de usuario cumplan estos requisitos para que Vertex AI Search para el comercio pueda generar resultados de calidad.

En esta sección se enumeran los siguientes elementos:

Si usas modelos de recomendaciones, consulta también los requisitos de datos de los tipos de modelos, donde se indican requisitos adicionales en función del tipo de modelo de recomendaciones y del objetivo de optimización que quieras usar.

Puede consultar las métricas de calidad de los datos de búsqueda en la página Calidad de los datos de la consola de búsqueda de comercio. Estas métricas muestran los porcentajes de productos y eventos de usuario que cumplen los estándares recomendados de calidad de los datos. Para obtener información sobre cómo ver la calidad de los datos de búsqueda, consulta Desbloquear niveles de rendimiento de búsqueda.

Requisitos generales de los eventos de usuario

Asegúrate de que tus eventos de usuario cumplan los siguientes requisitos para que Vertex AI Search para el sector del comercio pueda generar resultados de calidad. Se aplican tanto a las recomendaciones como a las búsquedas.

Tipo de evento Requisito Impacto
Todos los eventos

No incluyas datos sintéticos ni eventos duplicados.

Los eventos sintéticos o duplicados afectan negativamente a la calidad del modelo y, a menudo, impiden que el entrenamiento del modelo se lleve a cabo correctamente. Los eventos duplicados pueden provocar que los valores de las métricas sean incorrectos.

Incluya al menos 100 IDs de visitante únicos por cada tipo de evento ingerido.

De esta forma, se verifica que Vertex AI Search para el comercio tiene 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 de la API.

Usar un formato coherente para los IDs de visitante ayuda a identificar correctamente los patrones de los visitantes y a proporcionar resultados de mayor calidad basados en el comportamiento de los usuarios.

Los productos incluidos en los eventos deben estar en su catálogo de productos.

La proporción de eventos sin unir debe ser lo más baja posible. Una proporción alta puede afectar negativamente a la calidad de las recomendaciones o los resultados de búsqueda.

Los datos de eventos sin combinar no se usan para entrenar modelos. Sin embargo, los eventos no unidos se pueden unir más adelante, después de que se hayan insertado los productos asociados. Para obtener más información, consulta Volver a enviar 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 ha visto cinco páginas de detalles de producto, ha añadido tres productos al carrito y, después, ha comprado dos de los cinco productos originales. Si todos estos eventos proporcionan el mismo ID de visitante con un formato coherente, Vertex AI Search para el comercio puede tener en cuenta esa secuencia de comportamiento en sus modelos.

detail-page-view

Incluya exactamente un producto por evento.

El evento no se puede usar si no hay ningún producto. Si se incluyen varios productos, el evento tendrá un formato incorrecto y no se podrá usar.

add-to-cart

Incluya exactamente un producto por evento.

Si se incluyen varios productos, el evento tendrá un formato incorrecto y no se podrá 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.

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

No hay ningún código de moneda predeterminado, por lo que debe proporcionarse uno.

Si los eventos de compra no incluyen este campo, las métricas de ingresos serán incorrectas.

Comprueba que algunos eventos de compra incluyan varios productos.

Si hay algunos eventos de compra con varios productos, el modelo puede aprender patrones de compra conjunta.

Requisitos específicos de las recomendaciones

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

Si usas modelos de recomendaciones, consulta también los requisitos de datos de los tipos de modelos, donde se indican requisitos adicionales en función del tipo de modelo de recomendaciones y del objetivo de optimización que quieras usar.

Tipo de evento Requisito Impacto
purchase-complete

No convierta cestas con varios artículos en varios eventos de compra. Deben seguir siendo eventos de compra únicos que incluyan varios productos.

De esta forma, se verifica que se generen patrones de compra conjunta válidos.

Requisitos específicos de la Búsqueda

Si usas la búsqueda, asegúrate de que tus eventos de usuario cumplan 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.

Si no incluye este campo, puede afectar gravemente a la calidad de los resultados de búsqueda y a las métricas.

El ID de visitante de las solicitudes de búsqueda debe coincidir con el ID de visitante enviado en los eventos relacionados con esa solicitud de búsqueda.

Si no coinciden, los eventos estarán mal formados y las métricas podrían ser incorrectas.

La lista de IDs de producto de 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 búsqueda puede ser grave y las métricas serán incorrectas.

Si la búsqueda usa un filtro, filter debe existir y analizarse correctamente.

Si este campo no existe, Vertex AI Search para el comercio no podrá usar la parte del filtro de los datos, lo que puede afectar negativamente a la calidad de los resultados de búsqueda.

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

Si no incluye un token de atribución, se producirá un error en la búsqueda de comercio y se verá afectada negativamente la calidad de la búsqueda y la precisión de las métricas.

Requisitos de optimización de la búsqueda

Para 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 deben subirse al menos una vez al día, con un retraso máximo 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 necesitan al menos 250.000 eventos en los últimos 90 días para optimizar la experiencia de búsqueda en función de los eventos registrados.

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úrese de que la distribución de los datos se incline hacia la marca de tiempo más reciente. El número de eventos del último día con marca de tiempo debe ser igual o superior al recuento medio de eventos diarios.
Volumen de detail-page-view atribuido a un evento search 500.000 en los últimos 30 días Se necesitan al menos 500.000 eventos para optimizar los resultados de búsqueda con eventos de usuario.
Media 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 búsqueda con los eventos ingresados, 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 búsqueda con los eventos ingested.
Media de eventos add-to-cart atribuibles a un evento search por producto de pago 0,5 en los últimos 30 días Se recomienda para los resultados de búsqueda optimizados para conseguir ingresos.
Media de eventos purchase-complete atribuibles a un evento search por producto de pago que se puede buscar 0,5 en los últimos 30 días Se recomienda para los resultados de búsqueda optimizados para conseguir ingresos.

Requisitos de la personalización de la Búsqueda

La Búsqueda requiere los siguientes datos para personalizar la búsqueda de texto y los resultados de búsqueda por navegación 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 servidos por la búsqueda 100.000 en los últimos 30 días

Para ofrecer personalización,se necesitan al menos 100.000 eventos servidos por la búsqueda en los últimos 30 días.

Los resultados de 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 búsqueda de texto o de navegación si tienes previsto 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 supone un riesgo de exponer 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 búsqueda, la búsqueda podrá seguir personalizando los resultados de navegación. Por el contrario, si solo almacenas en caché los resultados de navegación, la búsqueda podrá seguir personalizando los resultados de búsqueda de consultas de texto.

Coincidencias de ID de visitante entre SearchRequests y eventos de usuario Más del 10% de los últimos 100.000 eventos de usuario Asegúrate de que el espaciado y el formato de los IDs de visitante coincidan en los eventos de SearchRequests y de usuario. El formato coherente del ID de visitante verifica que la búsqueda pueda identificar la actividad del usuario correctamente.

Ejemplos y esquemas de tipos de eventos de usuario

En esta sección se proporcionan los formatos de datos de cada tipo de evento admitido.

Se proporcionan ejemplos de píxel de JavaScript y Tag Manager. En el caso de BigQuery, se proporciona el esquema de tabla completo de cada tipo.

En 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 que:

  • El campo experimentIds solo es necesario si estás llevando a cabo un experimento A/B.
  • El campo attributionToken solo es obligatorio para Vertex AI Search para el sector del comercio. Se usa para medir el rendimiento. Los tokens de atribución no deben enviarse a predict, search y detail-page-view, ni a eventos de clic.
  • Asegúrate de que todos tus eventos usen una sola moneda, sobre todo si tienes previsto usar la consolaGoogle Cloud para obtener métricas de ingresos. La API Vertex AI Search para el sector del comercio no admite el uso de varias monedas por catálogo.

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

Añadir al carrito

A continuación, se muestra el formato de evento de usuario add-to-cart en un ejemplo que solo usa los campos obligatorios.

La cantidad de producto de un evento add-to-cart debe ser un valor incremental que represente la cantidad del producto asociado a ese evento de usuario específico. Por ejemplo, si se añaden dos unidades de un producto al carrito de la compra, el campo de cantidad de ese evento add-to-cart debe ser 2. En el caso de los eventos add-to-cart, incluya exactamente un producto por evento.

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

Es posible que se necesiten otros campos en función del método de la API que se utilice o si se usan campos adicionales. Por ejemplo, si el evento de usuario está asociado a una entidad, especifique el campo entity. Para obtener información detallada sobre cada campo y cuándo es obligatorio, consulta la documentación de referencia de la API UserEvent.

Píxel de JavaScript

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 de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios son REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con 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"
 }
]

Categoría vista de una página

A continuación, se muestra el formato del evento de usuario category-page-view.

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

Aunque normalmente solo hay una categoría asociada a una página, el campo pageCategories también admite una jerarquía de categorías, que puede proporcionar como lista.

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

Es posible que se necesiten otros campos en función del método de la API que se utilice o si se usan campos adicionales. Por ejemplo, si el evento de usuario está asociado a una entidad, especifique el campo entity. Para obtener información detallada sobre cada campo y cuándo es obligatorio, consulta la documentación de referencia de la API UserEvent.

Píxel de JavaScript

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 de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios son REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con 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 los datos de eventos de usuario detail-page-view.

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

En la mayoría de los casos, productDetails contiene detalles del producto asociado, a menos que se venda un paquete de artículos.

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

Es posible que se necesiten otros campos en función del método de la API que se utilice o si se usan campos adicionales. Por ejemplo, si el evento de usuario está asociado a una entidad, especifique el campo entity. Para obtener información detallada sobre cada campo y cuándo es obligatorio, consulta la documentación de referencia de la API UserEvent.

Píxel de JavaScript

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 de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios son REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con 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 solo se muestran los campos obligatorios del formato de evento de usuario home-page-view.

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

Es posible que se necesiten otros campos en función del método de la API que se utilice o si se usan campos adicionales. Por ejemplo, si el evento de usuario está asociado a una entidad, especifique el campo entity. Para obtener información detallada sobre cada campo y cuándo es obligatorio, consulta la documentación de referencia de la API UserEvent.

Píxel de JavaScript

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 de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios son REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con 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"
 }
]

Compra completada

A continuación, se muestra el formato de los datos de eventos de usuario purchase-complete.

En los siguientes ejemplos solo se muestran los campos obligatorios del formato de evento de usuario purchase-complete.

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

Es posible que se necesiten otros campos en función del método de la API que se utilice o si se usan campos adicionales. Por ejemplo, si el evento de usuario está asociado a una entidad, especifique el campo entity. Para obtener información detallada sobre cada campo y cuándo es obligatorio, consulta la documentación de referencia de la API UserEvent.

Píxel de JavaScript

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 de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios son REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con 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 de búsqueda mínimo requerido

Estos son los campos mínimos obligatorios para que Vertex AI Search para el sector del comercio devuelva una lista de resultados de 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 producto que se muestra al usuario final en la página de resultados de búsqueda.
  • userEvents captura toda la información de metadatos que necesita la API Retail sobre cómo interactúan los usuarios finales con el sitio web del cliente.

En los siguientes ejemplos solo se muestran 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 en RFC 3339.

Es posible que se necesiten otros campos en función del método de la API que se utilice o si se usan campos adicionales. Por ejemplo, si el evento de usuario está asociado a una entidad, especifique el campo entity. Para obtener información detallada sobre cada campo y cuándo es obligatorio, consulta la documentación de referencia de la API UserEvent.

Píxel de JavaScript

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 de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios son REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con 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 quieres usar la función Autocompletar. No es obligatorio para las búsquedas.

En los siguientes ejemplos se muestra el campo completionDetail cuando un usuario escribe "sh" y hace clic en la segunda sugerencia, "zapatos", de 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 de completeQuery.

selectedSuggestion debe ser igual que searchQuery.

Píxel de JavaScript

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 de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios son REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con 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 la compra

A continuación, se muestra el formato de los datos de eventos de usuario shopping-cart-page-view.

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

Proporciona los objetos productDetails y userEvents, a menos que el carrito de la compra esté vacío.

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

Es posible que se necesiten otros campos en función del método de la API que se utilice o si se usan campos adicionales. Por ejemplo, si el evento de usuario está asociado a una entidad, especifique el campo entity. Para obtener información detallada sobre cada campo y cuándo es obligatorio, consulta la documentación de referencia de la API UserEvent.

Píxel de JavaScript

var user_event = {
  "eventType": "shopping-cart-page-view"",
  "visitorId": "VISITOR-ID"
  "cartId": "CART-ID",
  "productDetails": [{
      "product": {
        "id": "PRODUCT-ID"
      },
      "quantity": PRODUCT-QUANTITY
    }]
};

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

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>

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

BigQuery

Este es el esquema JSON completo de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios son REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con 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 tabla siguiente 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 de usuario de Google Analytics 4, asegúrese de que sus eventos de usuario de Google Analytics 4 usen los siguientes campos para que Vertex AI Search for commerce pueda integrar sus datos correctamente.

Google Analytics 4 Comercio 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 definida como "currency"

Valor:
event_params.value.string_value		 productDetails.product.priceInfo.currencyCode
Clave:
event_params.key definida como "currency"

Valor:
event_params.value.string_value		 purchaseTransaction.currencyCode
Clave:
event_params.key definida como "search_term"

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

Siguientes pasos