Vertex AI Search para retail cambia su nombre a Vertex AI Search para el sector del comercio. Estamos actualizando el contenido para reflejar la nueva marca.

Esta página se ha traducido con Cloud Translation API.

Registrar eventos de usuario en tiempo real

En esta página se describe cómo registrar eventos de usuario en tiempo real. Vertex AI Search para el sector del comercio usa eventos de usuario en tiempo real para generar recomendaciones y resultados de búsqueda. Obtendrás mejores resultados cuantos más tipos de eventos de usuario registres con información de producto válida.

Los procedimientos de registro de esta página se aplican tanto a las recomendaciones como a las búsquedas. Una vez que haya registrado los datos, ambos servicios podrán usar esos eventos, por lo que no tendrá que subir los mismos datos dos veces si utiliza ambos servicios.

Antes de empezar

Antes de registrar eventos de usuario, debe tener lo siguiente:

Se ha creado un proyecto Google Cloud con la autenticación configurada.
Una clave de API válida (para JavaScript Pixel o Tag Manager) o una cuenta de servicio válida con el rol Editor de comercio asignado si se usa la API para escribir directamente.

Componentes necesarios

Token de atribución: habilita las métricas de rendimiento de los eventos de usuario registrados para captar las interacciones de los usuarios que usan un producto por primera vez en función de las recomendaciones o los resultados de búsqueda proporcionados anteriormente. Consulta más información sobre cómo incluir tokens de atribución.
IDs de visitante: se requieren al registrar eventos de usuario. Para obtener más información, consulta Información sobre los usuarios.

Consejos generales para registrar eventos de usuario

Sigue las prácticas recomendadas, como volver a unirte a los eventos, mantener tu catálogo actualizado y proporcionar la mayor cantidad de información posible.
Puedes consultar ejemplos de tipos de eventos de usuario y esquemas en formato JSON en la página Acerca de los eventos de usuario.

Prácticas recomendadas para registrar eventos de usuario

Vertex AI Search para el sector del comercio requiere datos de alta calidad para generar resultados de alta calidad. Si los datos están incompletos o son incorrectos, la calidad de los resultados se verá afectada.

Cuando registre eventos de usuario, asegúrese de implementar las siguientes prácticas recomendadas:

Si registras eventos de usuario antes o durante la importación del catálogo, vuelve a unir los eventos registrados antes de que se completara la importación del catálogo.

Puede importar el catálogo antes, después o al mismo tiempo que registra eventos de usuario. Hacer estas tareas en paralelo puede ahorrar tiempo si el catálogo es grande y hay muchos eventos de usuario. Una vez que se haya completado la importación del catálogo, debe usar la API para volver a asociar los eventos que se subieron antes de que se completara la importación.

Vertex AI Search for commerce intenta combinar los eventos de usuario registrados con los metadatos del catálogo de productos cuando se crea el evento de usuario. Solo se usan los eventos a los que se ha unido correctamente para el entrenamiento, así que asegúrate de volver a unirte a los eventos registrados antes de que se importara por completo el catálogo. Si un evento hace referencia a un elemento que no existe en el catálogo, se descarta o no se asocia a los productos correctos. Del mismo modo, si importa eventos de usuario antiguos, el catálogo debe incluir todos los productos a los que hagan referencia. Puede marcar los productos antiguos como OUT_OF_STOCK en lugar de eliminarlos del catálogo.
Mantenga su catálogo actualizado.

Cuando registra eventos de usuario, el producto incluido en el evento de usuario se conecta con su catálogo actual. Si registra un evento de un producto que no está en el catálogo actual, no se podrá usar para entrenar sus modelos. Esto se denomina evento "sin unir". Si has registrado eventos antes de que se importara por completo tu catálogo, debes volver a asociar los eventos que se registraron durante la importación. Es normal que haya algunos eventos sin unir. Sin embargo, si el porcentaje de eventos no unidos alcanza el 5% o más del total de eventos de usuario, asegúrate de que tu catálogo esté actualizado, vuelve a unir los eventos que se registraron antes de que el catálogo se actualizara por completo e investiga por qué se están creando eventos no unidos.

Puede ver los eventos a los que no se ha unido mediante el filtrado por eventos. Más información
Proporciona toda la información posible con tus eventos de usuario.

Cada tipo de evento de usuario tiene información diferente que se requiere y se acepta. Para obtener más información, consulta el artículo Acerca de los eventos de usuario.
Configura alertas de Cloud Monitoring para saber si tus procesos de registro de eventos de usuario sufren alguna interrupción.
En el caso de las importaciones masivas de eventos de usuario, limite el tamaño de los datos que importe.

Una importación masiva de eventos de usuario puede tardar hasta 24 horas en completarse.

El tamaño de cada archivo debe ser de 2 GB como máximo. Puedes incluir un máximo de 100 archivos en una única solicitud de importación. Una opción es importar solo los eventos de usuario de un día cada vez.
Después de una importación en bloque, consulte los informes de errores para asegurarse de que los datos se han importado correctamente.
Cuando importe datos de eventos de usuario, incluya una marca de tiempo precisa para cada evento de usuario y evite importar eventos de usuario secuenciales con marcas de tiempo idénticas.

Proporciona la marca de tiempo en el campo eventTime con el formato especificado en RFC 3339.
Si has importado eventos de usuario incorrectos, ponte en contacto con tu representante de Vertex AI Search for commerce para saber cómo solucionar el problema.
Cuando sea posible, mantenga los datos de eventos de usuario de forma continua.

Las lagunas en los datos de eventos de usuario pueden reducir la calidad del modelo.
Usa una forma segura de un identificador único para mantener el anonimato de los usuarios en Vertex AI Search para el comercio y proteger la privacidad de tus usuarios. Es tu responsabilidad ocultar la información personal identificable (IPI), como las direcciones de correo o de casa, de tus datos.

Tutorial para escribir eventos de usuario

En este tutorial se explica cómo registrar eventos de usuario con el método userEvents.write.

Para seguir las instrucciones paso a paso de esta tarea directamente en el editor de Cloud Shell, haz clic en Ayúdame:

Guíame

Formas de enviar eventos de usuario

Puedes registrar un evento de usuario de varias formas:

Usa el píxel de JavaScript.
Se recomienda usar Google Analytics 4 (GA4) con Tag Manager.
Envía eventos directamente a la API desde tu servidor backend mediante el método user.Events.write.
Tag Manager, por sí solo o junto con Google Analytics 4.
Con el etiquetado del lado del servidor, puede registrar eventos implementando un solo contenedor de servidor con muchos clientes posteriores.

Registrar eventos de usuario con un píxel de JavaScript

En el siguiente ejemplo se registra un detail-page-view UserEvent mediante un píxel de JavaScript.

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "experimentIds": "experiment-id",
  "productDetails": [
      {
        "product": {"id": "123"}
      }
  ]
};

var _gre = _gre || [];
// Credentials for project.
_gre.push(['apiKey', 'api-key']);
_gre.push(['logEvent', user_event]);
_gre.push(['projectId', 'project-id']);
_gre.push(['locationId', 'global']);
_gre.push(['catalogId', 'default_catalog']);

(function() {
  var gre = document.createElement('script'); gre.type = 'text/javascript'; gre.async = true;
  gre.src = 'https://www.gstatic.com/retail/v2_event.js';
  var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(gre, s);
})();

</script>

Si ha importado eventos de usuario con Google Analytics 360, defina visitorID como el ID de cliente de Google Analytics. Tenga en cuenta que el ID de cliente de Google Analytics solo forma parte del nombre completo de la cookie _ga (por ejemplo, el ID de cliente 123456789.123456789 forma parte de la cookie _ga GA1.3.123456789.123456789).

A continuación, se muestra un ejemplo abreviado del formato para definir el ID de cliente en un evento de usuario. Sustituya "G-XXXXXX" por su ID de seguimiento de Google Analytics.

<script type="text/javascript">
var tracker = ga.getByName('G-XXXXXX');
var user_event = {
      "visitorId": tracker.get('clientId')
};
</script>

Registrar eventos de usuario con el método `userEvents.write`

Puedes usar el método userEvents.write para enviar eventos de usuario directamente a la API desde tu servidor backend.

Para registrar eventos de usuario, envía una solicitud POST al método userEvents.write e indica el cuerpo de solicitud adecuado.

curl

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data "{
         'eventType': 'detail-page-view',
         'visitorId': 'visitor0',
         'eventTime': '2020-01-01T03:33:33.000001Z',
         'experimentIds': ['321'],
         'attributionToken': 'ABC',
         'attributes': {
            'example_text_attribute': {
              'text': ['text_1', 'text_2']
            },
            'example_number_attribute': {
               'numbers': [3.14, 42, 1.2345]
            }
         },
         'productDetails': [{
           'product': {
             'id': 'abc'
           }
          }],
         'userInfo': {
           'userId': 'abc',
           'ipAddress': '8.8.8.8',
           'userAgent': 'Mozilla/5.0',
           'directUserRequest': true
         },
         'uri': 'http://example',
         'referrerUri': 'http://example',
         'pageViewId': 'currentPageUri'
}" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:write"

Java

public static UserEvent writeUserEvents(UserEvent eventToWrite)
    throws IOException, InterruptedException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  WriteUserEventRequest request = WriteUserEventRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setUserEvent(eventToWrite)
      .build();

  UserEvent writtenUserEvent = userEventsClient.writeUserEvent(request);

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return writtenUserEvent;
}

Registrar eventos de usuario con Google Analytics 4

Puede registrar datos de eventos de usuario de Google Analytics 4 en Vertex AI Search for commerce.

Comprobar la fuente de datos

Asegúrese de que los datos de eventos de usuario que quiere importar tienen el formato correcto.

Para ver una tabla de los campos de Google Analytics 4 que usa Vertex AI Search para el comercio y a qué campos de Vertex AI Search para el comercio se asignan, consulte Campos de eventos de usuario de Google Analytics 4.

Para ver todos los parámetros de evento de Google Analytics, consulta la documentación de referencia de eventos de Google Analytics.

Comprueba que:

Si importa eventos de compra, que requieren algunos modelos de Vertex AI Search for commerce, sus informes de eventos incluyen códigos de moneda. Consulte los parámetros de evento purchase en la documentación de Google Analytics.
Si tiene previsto importar eventos search, sus informes de eventos incluirán consultas de búsqueda.

Se pueden importar eventos search, pero estos no se asignan desde Google Analytics 4 de la misma forma que otros tipos de eventos, ya que Google Analytics 4 no admite de forma nativa el tipo de evento search de Vertex AI Search for commerce.search Durante la importación, se crean eventos de search a partir de Google Analytics 4 combinando información de los parámetros de evento view_item_list y search_term.

Consulte los parámetros de evento search en la documentación de Google Analytics.

Registrar eventos de Google Analytics 4

Para registrar un evento de usuario, incluya datos JSON sin formato codificados en URL para el evento en su llamada al método userEvents.collect.

En el parámetro prebuilt_rule, use el valor ga4_bq.

Para que sea más fácil de leer, en el siguiente ejemplo de uso de la llamada userEvents.collect, primero se define GA4_EVENT como una variable que contiene los datos JSON sin procesar de un evento de ejemplo. La llamada userEvents.collect del ejemplo codifica mediante URL los datos del evento con la variable GA4_EVENT.

Para facilitar la codificación de URLs más adelante, puede definir GA4_EVENT como una variable que contenga datos de eventos. En este ejemplo se muestra un evento add-to-cart.

GA4_EVENT='{
  "event_timestamp": 1622994083878241,
  "event_name": "add_to_cart",
  "user_pseudo_id": "352499268.1622993559",
  "items": [
    {
      "item_id": "11",
      "price": 29.99,
      "quantity": 3
    }
  ],
  "event_params": [
    {
      "key": "currency",
      "value": {
        "string_value": "CAD"
      }
    }
  ],
  "user_id": "Alice"
}'

Haz una llamada userEvents.collect que incluya los datos JSON sin formato codificados en URL de un evento de usuario:

curl \
-G \
--data-urlencode "raw_json=${GA4_EVENT}" \
-i \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:collect?key=EXAMPLEKEY1&prebuilt_rule=ga4_bq'"

Registrar eventos de usuario con Google Tag Manager

Tag Manager te permite gestionar y probar varias etiquetas sin tener que hacer muchos cambios en el código del lado del servidor de tu sitio.

Algunas de las decisiones que tomes durante la configuración dependerán de si usas Google Analytics y Google Analytics Ecommerce. El comercio electrónico de Google Analytics se puede implementar con Google Analytics 4 o con Comercio electrónico mejorado. La etiqueta de Cloud Retail admite ambas opciones.

No es necesario usar Google Analytics ni Google Analytics Ecommerce. Si no los usa, puede configurar Variable - Ecommerce (para usar el esquema de comercio electrónico de GA4) o Variable - Cloud Retail (para usar el esquema de Vertex AI Search for commerce) al crear la etiqueta de Cloud Retail y rellenar manualmente el código de la capa de datos de su sitio después de crear la etiqueta.

Comercio electrónico de Google Analytics es una configuración adicional de Google Analytics que envía a Google Analytics títulos, IDs y precios de productos, detalles de transacciones y otros datos de comercio electrónico estructurados. Vertex AI Search for commerce puede usar automáticamente la capa de datos de comercio electrónico de Google Analytics, por lo que, si ya la ha configurado, la configuración puede ser más sencilla. Si no ha configurado la función de comercio electrónico de Google Analytics, pero quiere usarla, consulte más detalles e instrucciones de configuración en la guía para desarrolladores de GA4.

Siga este procedimiento único para configurar una etiqueta de Cloud Retail en Tag Manager y registrar eventos de usuario.

Crear una variable de ID de visitante

El valor visitorId se usa para hacer un seguimiento de los usuarios. visitorId suele ser un ID de sesión y es obligatorio para todos los eventos. Configura una variable que defina los IDs de sesión como visitorId.

Si usas Google Analytics, puedes usar el ID de visitante de Google Analytics. Para configurar esta opción, siga el procedimiento que se indica a continuación para anular el valor del ID de visitante de la etiqueta de Cloud Retail. De esta forma, se asigna la cookie propia "_ga" a una variable de Tag Manager llamada "GA visitorId". Puede hacer lo mismo con cualquier cookie de ID de sesión; no tiene por qué ser de Google Analytics.

En este procedimiento se da por supuesto que usa Google Analytics. Si no es así, puede usar otra cookie o variable, u obtener el ID de visitante de la capa de datos cloud_retail.

Para asignar el valor visitorID a una variable de la etiqueta de Cloud Retail, sigue estos pasos:

En Tag Manager, ve a la pestaña Variables y haz clic en Nueva para crear una variable definida por el usuario.
Asigne un nombre a la variable en la parte superior del cuadro de diálogo, como "visitorId de GA".
Introduce la configuración de la variable.

Puede usar el ID de cliente o el ID de cookie como fuente de los IDs de visitante. Utilice siempre una fuente de ID de visitante coherente al ingerir eventos de usuario históricos y en tiempo real.
ID de cliente
En Google Analytics 4, esta variable se asigna al campo user_pseudo_id del esquema de exportación de BigQuery de Google Analytics 4.
1. En Tipo de variable, selecciona JavaScript personalizada.
2. Introduzca la siguiente secuencia de comandos en el campo JavaScript personalizado.
  
  Sustituya "G-XXXXXX" por su ID de seguimiento de Google Analytics. Para encontrar su ID de seguimiento, consulte ¿Qué ha ocurrido con mi ID de seguimiento?
  function() { var tracker = ga.getByName('G-XXXXXX'); return tracker.get('clientID'); }
3. Haz clic en Guardar para guardar la variable.
ID de cookie
1. Seleccione Cookie propia como tipo de variable.
2. En el campo Cookie Name (Nombre de la cookie), introduzca _ga.
3. Haga clic en Formato de valor, seleccione Convertir indefinido en... e introduzca "" (una cadena vacía).
4. Haz clic en Guardar para guardar la variable.
  
  De esta forma, la cookie propia "_ga" se asigna a una variable de Tag Manager llamada "GA visitorId".

A continuación, cree una etiqueta de Cloud Retail en Tag Manager. Esta etiqueta usará la variable de ID de visitante que acabas de crear.

Crear una etiqueta de Google Tag Manager

Configura una etiqueta en Tag Manager para enviar información de eventos de usuario a Vertex AI Search para el comercio.

Inicie sesión en Tag Manager y seleccione el contenedor de su sitio.
Vaya a la pestaña Etiquetas y haga clic en Nueva para añadir una etiqueta.
En la parte superior del panel, asigna un nombre a la etiqueta (el texto de marcador de posición es Variable sin título), como "Vertex AI Search para el sector del comercio".
Haga clic en Configuración de la etiqueta y elija la etiqueta Cloud Retail para abrir el panel de configuración de la etiqueta.
Introduce tu clave de API.

Usa la clave que has creado al configurar Vertex AI Search para el comercio.

Puedes acceder a tus claves de API desde la página APIs y servicios > Credenciales de la consola de Google Cloud .
Introduce el número del proyecto en el que se ha habilitado Vertex AI Search para el sector del comercio. Google Cloud

Puedes consultar el número de proyecto en el Google Cloud panel de control de la consola.
En el campo Fuente de datos de eventos de usuario, haga lo siguiente:
- Capa de datos (opción recomendada): seleccione esta opción si su implementación es una de las siguientes:
  - Ha implementado el comercio electrónico de Google Analytics a través de Tag Manager. Reutilice la capa de datos como fuente de datos de eventos en lugar de rellenar una nueva. Usa el esquema de Google Analytics 4, si está presente. De lo contrario, usa Comercio electrónico mejorado de UA. Con esta fuente de datos, solo puede registrar eventos add-to-cart, purchase-complete, detail-page-view y search. Los eventos search se registran mediante impresiones de comercio electrónico combinadas con consultas de búsqueda (consulte Crear una variable de consulta de búsqueda).
  - Usa el comercio electrónico de Google Analytics y puede rellenar manualmente el código de la capa de datos. Consulta la guía para desarrolladores de Tag Manager.
- Variable, Cloud Retail: selecciona esta opción para rellenar una variable de Tag Manager con los campos obligatorios de Vertex AI Search para el sector del comercio. Puede elegir esta opción si no usa la función de comercio electrónico de Google Analytics o si esta no tiene los datos necesarios para Vertex AI Search for commerce. Si va a cambiar a esta fuente desde la opción Capa de datos - Cloud Retail antigua, cree también una variable de capa de datos con la clave cloud_retail y asóciela a la opción Variable - Cloud Retail.
- Variable, comercio electrónico: selecciona esta opción si no usas el comercio electrónico de Google Analytics en tu capa de datos y no puedes rellenar manualmente el código de la capa de datos, pero quieres usar el esquema de comercio electrónico de Google Analytics. También es útil si ha implementado el comercio electrónico de Google Analytics, pero quiere aumentar o cambiar los valores de la capa de datos. Después, puede combinar esos valores en una variable personalizada con el formato del esquema de comercio electrónico de Google Analytics que pueda usar la etiqueta de Cloud Retail.
  
  En el campo Leer datos de comercio electrónico de una variable de usuario que aparece, elija una variable. De esta forma, Vertex AI Search para el comercio puede leer los datos de eventos de usuario de comercio electrónico de Google Analytics a partir de una variable personalizada que cree.
  
  La variable debe tener el formato que se indica en la guía para desarrolladores de GA4. Para crear una variable con el formato correcto, puede usar el generador de objetos de comercio electrónico mejorado, una plantilla de variable personalizada de la galería de plantillas de la comunidad de Tag Manager. Google no se encarga del mantenimiento de las plantillas comunitarias. Para usar esta plantilla, consulta la página de la galería del creador de objetos de comercio electrónico mejorado, donde encontrarás documentación y otros recursos.
Haz clic en el botón + Sobrescribir un valor del mensaje UserEvent.
En Selector de campo, seleccione visitorId como campo y, en Valor de campo, seleccione la nueva variable de ID de visitante que ha creado en Crear una variable de ID de visitante.
Haz clic en Guardar.

Se ha creado tu etiqueta de Cloud Retail.

Opciones de fuentes de datos antiguas

Antes, Capa de datos - Comercio electrónico y Capa de datos - Cloud Retail estaban disponibles como opciones de fuente de datos. Estas opciones antiguas no están disponibles en las nuevas etiquetas. Si cambia una etiqueta por una nueva fuente de datos, previsualícela con Tag Manager para verificarla antes de implementarla. Al cambiar:

Si ha usado Capa de datos - Comercio electrónico, puede cambiar a Capa de datos. Si está presente, se usa el esquema de Google Analytics 4. De lo contrario, usa Comercio electrónico mejorado de UA.
Si ha usado Capa de datos - Cloud Retail, cambie a la opción Variable - Cloud Retail. Crea una variable de capa de datos con la clave cloud_retail y asóciala a la opción Variable - Cloud Retail.

Si usas la búsqueda, crea una variable para las consultas de búsqueda y adjúntala a la nueva etiqueta.
Crea activadores de eventos para tu etiqueta.

Crear una variable de consulta de búsqueda

Si usas la búsqueda, puedes crear una variable en Tag Manager para las consultas de búsqueda y adjuntarla a tu etiqueta de Cloud Retail. De esta forma, Vertex AI Search para el comercio puede obtener consultas de búsqueda de Analytics.

Los tipos de variables que cree dependerán de su fuente de datos de eventos de usuario.

Variable - Comercio electrónico o la capa de datos con el esquema de comercio electrónico de Google Analytics: cree una variable de URL o de elemento del DOM en Tag Manager y adjúntela a su etiqueta de Cloud Retail. Además, habilita la opción para que tu etiqueta use las impresiones de comercio electrónico de Google Analytics para crear eventos de búsqueda.
Variable - Cloud Retail o una capa de datos rellenada manualmente: Cree una variable de URL o de elemento del DOM en Tag Manager y adjúntela a su etiqueta de Cloud Retail. Para determinar si el tipo de un evento de usuario es search, también debe hacer lo siguiente:
- Crea una variable de tipo constante para los tipos de evento de búsqueda y adjúntala a tu etiqueta.
- Defina el tipo de evento de búsqueda en su capa de datos o variable de Cloud Retail.

Crear y adjuntar una variable de Tag Manager para las consultas de búsqueda

Si usa la búsqueda, puede crear una variable de URL, de elemento DOM o de JavaScript personalizado que se rellene con las consultas de búsqueda introducidas en su sitio.

Como alternativa a este procedimiento, puede configurar la capa de datos para que proporcione información sobre las consultas de búsqueda. Sin embargo, puede usar variables de Tag Manager si no tiene acceso a la capa de datos o si prefiere no configurarla.

Puede crear una variable de tipo URL, una variable de tipo elemento del DOM o una variable de JavaScript personalizada (de página). El tipo de cookie que crees y cómo la configures dependerá de la implementación de tu sitio:

Una variable de URL obtiene las consultas de búsqueda de las URLs de resultados de búsqueda de su sitio. Use esta variable si su sitio incluye la cadena de consulta en la URL de sus resultados de búsqueda.
Una variable de elemento DOM obtiene la información de la consulta de búsqueda del modelo de objetos del documento (DOM) de su sitio. No es necesario editar el DOM para usar esta variable. Sin embargo, debes poder leer y entender el DOM para configurar esta variable correctamente.
Una variable de JavaScript personalizado devuelve datos con el formato de una función de JavaScript. Esto resulta útil si ya tiene datos que quiere formatear con el esquema Cloud Retail o Comercio electrónico.

Primero, cree una variable de Tag Manager de tipo URL, elemento DOM o JavaScript personalizado:

En Tag Manager, ve a la pestaña Variables y haz clic en Nueva para crear una variable definida por el usuario.
Asigne un nombre a la variable en la parte superior del cuadro de diálogo, como "search_variable".
Indica la configuración de la variable:
Tipo de URL
1. En Tipo de variable, selecciona URL.
2. En Tipo de componente, seleccione Consulta.
3. Si especifica una clave de consulta, asígnela a la clave que precede a la consulta de búsqueda en su URL.
  
  Por ejemplo, si la URL es http://example.com/?q=shoes, la clave de consulta es q. En este ejemplo, el valor de la variable se asignaría a shoes.
Tipo de elemento DOM
1. En Tipo de variable, selecciona Elemento DOM.
2. Defina Método de selección e introduzca el ID del elemento o el selector del elemento de la consulta de búsqueda.
  
  Este ajuste depende de si tu sitio usa un ID de elemento o un selector de CSS para identificar la consulta de búsqueda.
3. Si especifica un atributo, asígnelo al atributo que contenga el término de consulta de búsqueda.
  
  Por ejemplo, si la consulta de búsqueda de su DOM es <id="search" value="shoes">, el atributo sería value. En este ejemplo, el valor de la variable sería shoes.
Tipo de JavaScript personalizado
1. En Tipo de variable, selecciona JavaScript personalizada.
2. Sustituye las variables del siguiente código y pégalo en el panel JavaScript personalizado.
3. En el panel JavaScript personalizado, añada código JavaScript que devuelva un evento de búsqueda en el esquema de comercio.
  
  El siguiente código de ejemplo transforma los datos de una variable Ecommerce Items en la matriz productDetails que usa el esquema de Vertex AI Search para el comercio y devuelve un evento completo. Para usar este código, sustituye Ecommerce Items, Search Query y Search Filter por variables en tu implementación de Tag Manager.
  function () { var retail; var items = []; for (var i = 0; i < {{Ecommerce Items}}.length; i++) { var item = {'product': { 'id': {{Ecommerce Items}}[i].item_id } }; items.push(item); } retail = { 'eventType': 'search', 'searchQuery': '{{Search Query}}', 'filter': '{{Search Filter}}', 'productDetails': items } return retail; }
Haz clic en Guardar para guardar la variable.

A continuación, adjunta la variable a tu etiqueta de Cloud Retail:

En la página Tag Manager (Gestor de Etiquetas), Etiquetas, haga clic en su etiqueta Cloud Retail para editarla.
Si la fuente de datos de eventos de usuario de su etiqueta es Variable - Ecommerce (Variable - Comercio electrónico) o utiliza la capa de datos con el esquema de comercio electrónico de Google Analytics, marque la casilla Use enhanced ecommerce impressions to construct search events (Usar impresiones de comercio electrónico mejorado para crear eventos de búsqueda).

De esta forma, Vertex AI Search para el comercio puede determinar si el tipo de evento de un usuario es search en función de los datos de búsqueda que obtiene de esta etiqueta.
En la sección Datos de eventos de usuario, haga clic en el botón + Sobrescribir un valor del mensaje UserEvent.
Selecciona searchQuery en Selector de campos y define tu variable de consulta de búsqueda como Valor de campo.
Guarde la etiqueta.

Si ha elegido usar una variable de Cloud Retail o una capa de datos rellenada manualmente como fuente de eventos de usuario de su etiqueta de Cloud Retail, consulte Crear y adjuntar una variable constante.
Crea activadores de eventos para tu etiqueta.

Crear y adjuntar una variable constante

Puede seguir este procedimiento si ha elegido Variable - Cloud Retail (Variable - Cloud Retail) o una capa de datos rellenada manualmente como fuente de eventos de usuario de su etiqueta de Cloud Retail.

Si crea una variable de tipo constante para los eventos de búsqueda y la define como una anulación de evento de usuario en su etiqueta de Cloud Retail, Vertex AI Search para el comercio podrá determinar si el tipo de un evento de usuario es search.

Como alternativa a este procedimiento, puede especificar el tipo de evento de usuario search mediante la capa de datos o la variable de Cloud Retail que sirve como fuente de eventos de su etiqueta. De lo contrario, sigue estos pasos para definir el tipo de evento.

Primero, crea una variable de tipo constante:

En Tag Manager, ve a la pestaña Variables y haz clic en Nueva para crear una variable definida por el usuario.
Asigne un nombre a la variable en la parte superior del cuadro de diálogo, como "search_constant".
En Tipo de variable, selecciona Constante.
Introduce search en el campo Valor.
Haz clic en Guardar para guardar la variable.

A continuación, adjunta la variable a tu etiqueta de Cloud Retail:

En la página Tag Manager (Gestor de Etiquetas), Etiquetas, haga clic en su etiqueta Cloud Retail para editarla.
En la sección Datos de eventos de usuario, haga clic en el botón + Sobrescribir un valor del mensaje UserEvent.
Selecciona eventType en Selector de campos y define tu variable de consulta de búsqueda como Valor de campo.
Guarde la etiqueta.

A continuación, crea activadores de eventos para tu etiqueta.

Crear activadores de eventos para su etiqueta de Tag Manager

Crea activadores para todos los tipos de eventos de usuario que usarán tus modelos de Vertex AI Search for commerce.

Las etiquetas de Tag Manager deben tener activadores que controlen cuándo se deben activar en el sitio. Los activadores detectan cuándo se producen eventos (por ejemplo, cuando un usuario ve la página principal o añade un artículo al carrito) y le indican a la etiqueta que envíe la información de ese evento de usuario a Vertex AI Search for commerce.

Tag Manager ofrece algunos activadores estándar. Por ejemplo, Window Loaded es un activador de eventos detail-page-view. Para obtener más información sobre cada tipo, consulta Tipos de activadores en la documentación de Tag Manager.

Normalmente, la etiqueta se activará cuando un usuario vea cualquier página que tenga los eventos necesarios para Vertex AI Search para el comercio (como la página principal, las páginas de detalles del producto, las páginas del carrito o la página de finalización de la compra). En estos casos, la etiqueta debe activarse después de que se haya cargado la página para que las cookies estén disponibles y se rellenen todas las variables de la capa de datos. Para ello, configure los activadores para que se activen en Carga de la ventana o DOM preparado.

Es posible que tenga que activar la etiqueta cuando se realice una acción en lugar de al cargar la página (por ejemplo, si un usuario añade un artículo al carrito y no se recarga la página). En estos casos, puede configurar esa acción de clic en su sitio para que envíe actualizaciones a la capa de datos simultáneamente y asocie el activador a esa acción.

Por ejemplo, si ha creado un activador para eventos add-to-cart, puede elegir el tipo de activador Clic - Solo enlaces y configurarlo para que se active con el ID de clic (en este ejemplo, addtocart). A continuación, configuraría el enlace addtocart de su sitio para que también actualice la capa de datos con nuevos valores cuando se haga clic en él:

  <a id="addtocart" href="javascript:void(0);"
         onclick="dataLayer.push({
                  'cloud_retail': {
                  'eventType': 'add-to-cart',
                  'visitorId': '456',
                  'cartId': 'mobile',
                  'productDetails': [{
                  'product': {
                  'id': '54321'
                  },
                  'quantity': 1
                  }]}});">Add to Cart</a>

En el caso de algunos eventos de usuario, debe crear un activador personalizado. Por lo general, se crea un activador personalizado en Tag Manager con el nombre del evento de usuario. Si no puede modificar el código de su frontend, puede crear un activador personalizado con macros de JavaScript. Para obtener más información sobre los activadores personalizados, consulte Activador de evento personalizado.

Siga estos procedimientos para crear activadores en Tag Manager:

Si no tienes activadores configurados: Crea activadores para tu etiqueta de Tag Manager
Si ya ha configurado los activadores de comercio electrónico de Google Analytics: puede reutilizar los activadores que configuró para el comercio electrónico de Google Analytics en lugar de crear otros nuevos. Consulta Reutilizar los activadores de comercio electrónico de Google Analytics.

Crear activadores para la etiqueta de Tag Manager

Si no usa el comercio electrónico de Google Analytics, cree activadores de eventos para los eventos de usuario que necesiten sus modelos de Vertex AI Search para el comercio. A continuación, asocia los nuevos activadores a la etiqueta de Cloud Retail que has creado en Tag Manager.

Antes de seguir los pasos que se indican a continuación, asegúrese de haber creado una etiqueta de Cloud Retail en Tag Manager. Consulta Crear una etiqueta de Tag Manager.

Primero, crea los activadores. Repita este procedimiento con todos los eventos de usuario que requieran sus modelos de Vertex AI Search para el comercio:

En la página Tag Manager, Activadores, haga clic en Nuevo > Configuración del activador.
Elige el tipo de activador que se aplique al evento de usuario para el que vas a crear un activador.
Guarda el activador.

A continuación, asocia los nuevos activadores a tu etiqueta de Cloud Retail. Este es un procedimiento que solo se realiza una vez:

En la página Tag Manager (Gestor de Etiquetas), Etiquetas, haga clic en su etiqueta Cloud Retail para editarla.
Haz clic en Activación, selecciona los nuevos activadores y haz clic en Añadir.
Guarde la etiqueta.

A continuación, previsualiza la etiqueta y configura la monitorización de errores de registro de eventos y otros problemas para asegurarte de que los datos se sigan recibiendo correctamente.

Si usas la capa de datos cloud_retail como fuente de eventos de usuario, asegúrate de configurarla también.

Reutilizar activadores de comercio electrónico de Google Analytics

Si ha implementado el comercio electrónico de Google Analytics con Tag Manager, reutilice los activadores de eventos de su comercio electrónico de Google Analytics para la búsqueda de Vertex AI para comercio.

Con esta fuente de datos, solo puede registrar eventos add-to-cart, purchase-complete, detail-page-view y search. Los eventos search se registran mediante impresiones de comercio electrónico combinadas con consultas de búsqueda (consulte Crear una variable de consulta de búsqueda).

En la siguiente tabla se muestra cómo se asignan los eventos de comercio electrónico y de comercio electrónico mejorado de Google Analytics a los eventos de Vertex AI Search para el comercio.

Google Analytics 4	Comercio electrónico mejorado	Vertex AI Search para el sector del comercio
`add_to_cart`	`add`	`add-to-cart`
`purchase`	`purchase`	`purchase-complete`
`view_item`	`detail`	`detail-page-view`
`view_item_list` o `view_search_results`	`impressions`	`search` (si se combina con el campo `searchQuery`)

Antes de empezar, asegúrate de que has hecho lo siguiente:

Configure una etiqueta de tipo Google Analytics: evento de GA4 en Tag Manager y habilite el comercio electrónico mejorado o GA4 en ella. Consulte la documentación de Tag Manager y la guía para desarrolladores de GA4 para obtener más información.
Ha configurado su etiqueta de comercio electrónico mejorado o de GA4 en Tag Manager para que se active en los eventos de usuario que tiene previsto registrar en Vertex AI Search para el comercio.
Ha creado una etiqueta de Cloud Retail en Tag Manager con "Capa de datos" o "Variable - Comercio electrónico" como fuente de datos de eventos de usuario (consulte Crear una etiqueta de Tag Manager).

Para reutilizar los activadores de comercio electrónico de Google Analytics, sigue estos pasos:

En la página Etiquetas de Tag Manager, haga clic en su etiqueta de comercio electrónico de Google Analytics (tipo Google Analytics: evento de GA4) para editarla.
En Configuración avanzada > Secuenciación de etiquetas, seleccione Activar una etiqueta después de que se active <nombre de la etiqueta de comercio electrónico mejorado o de GA4>.
Seleccione su etiqueta de Cloud Retail como Etiqueta de limpieza.

Seleccione No active <nombre de la etiqueta de Cloud Retail> si <nombre de la etiqueta de Comercio electrónico mejorado o de GA4> no se activa o está en pausa.
Guarde la etiqueta.

A continuación, previsualiza la etiqueta y configura la monitorización de errores de registro de eventos y otros problemas para asegurarte de que los datos se sigan recibiendo correctamente.

Si usas la capa de datos cloud_retail como fuente de eventos de usuario, asegúrate de configurarla también.

Usar la capa de datos `cloud_retail` con Tag Manager

Si ha creado su etiqueta de Cloud Retail en Tag Manager para usar la capa de datos cloud_retail como fuente de eventos de usuario, configure la variable dataLayer en su HTML de origen como se describe en la guía para desarrolladores de Tag Manager.

Acerca de la capa de datos

La mayoría de las etiquetas de Tag Manager requieren datos que cambian en función del usuario o de la página (como los IDs de usuario o los IDs de producto). En el caso de la etiqueta de Cloud Retail, esos datos deben exponerse de forma estructurada mediante una capa de datos para que Tag Manager pueda usarlos.

La capa de datos es un objeto JavaScript que se suele añadir a una página mediante código de servidor o, en el frontend, mediante HTML o una plantilla. Si una página está configurada con la capa de datos, contendrá un código similar al siguiente:

dataLayer = dataLayer || [];
dataLayer.push({
  'cloud_retail': {
    'eventType': 'home-page-view',
    'visitorId': 'visitor_a',

    'userInfo': {
      'userId': '789'
    },
  }
});

Este código crea un objeto dataLayer y le asigna la estructura cloud_retail como elemento de una matriz.

Campos obligatorios en la capa de datos `cloud_retail`

En Acerca de los eventos de usuario se indican todos los campos obligatorios y ejemplos de tipos de eventos que se deben enviar a la capa de datos cloud_retail.

Tu código o tus plantillas del lado del servidor deben tener las etiquetas de script correctas en cada página desde la que quieras enviar eventos. Una vez que el objeto dataLayer se haya rellenado correctamente en cada página, podrás probar la etiqueta Cloud Retail.

Algunos campos, como visitorId, son obligatorios para el mensaje UserEvent , pero puede que no estén disponibles al rellenar la capa de datos. Por ejemplo, visitorId puede derivarse de la cookie del usuario y experimentIds, del marco de experimentación A/B. En este caso, usa una variable para sobrescribir el campo de la etiqueta de Tag Manager.

Puedes sobrescribir los siguientes campos:

visitorId
userInfo.userId
attributionToken
experimentIds

Para saber cómo sobrescribir un campo UserEvent en Tag Manager, consulta el artículo Definir el campo visitorID en Tag Manager, en el que se explica cómo sobrescribir el valor del campo visitorId con una variable definida por el usuario.

En el siguiente ejemplo se muestra la capa de datos que debe incluir en su página para un detail-page-view UserEvent con Tag Manager:

<script>
  dataLayer = dataLayer || [];
  dataLayer.push({
    'cloud_retail': {
      'eventType' : 'detail-page-view',
      'visitorId': 'visitor_a',
      'userInfo': {
          // The user and visitor ID fields can typically be
          // be populated from a client-side JavaScript
          // variable such as a cookie. If you set the user
          // and/or visitor ID values from the server,
          // populate the `userID`.
          'userId': 'user_a'
      },
      // In most cases, the experiment ID field is populated from a
      // client side JavaScript variable as defined by the experiment
      // manager.
      // If you set the experiment ID value from the server,
      // populate the `experimentIds` field here.
      'productDetails': [
            {
              'product': {'id': '123'}
            }
      ],
    // You can use the 'cloud_retail' data layer element along with other
    // data layer elements.
    'ecommerce': {
      ...
    },
  }];
</script>

Previsualizar una etiqueta de Tag Manager

El modo de vista previa de Tag Manager le permite probar nuevas etiquetas antes de publicarlas en su sitio activo.

Para obtener más información sobre el modo de vista previa, consulta la documentación de Tag Manager sobre el modo de vista previa.

Siga este procedimiento para confirmar que la etiqueta se activa correctamente.

En la página Descripción general de Tag Manager, haga clic en Vista previa.

El modo de vista previa de Tag Manager se abre en una nueva pestaña del navegador.
Introduce la información de tu sitio y haz clic en Iniciar para iniciar Tag Assistant.

En la pestaña del navegador actual, se inicia Tag Assistant y tu sitio se abre en una pestaña nueva.
En su sitio, vaya a cualquier página en la que se deba activar la etiqueta de Cloud Retail.
Compruebe que Tag Assistant muestra la etiqueta de Cloud Retail en la pestaña Etiquetas de la sección Etiquetas activadas.
En Tag Assistant, vaya a la pestaña Capa de datos y compruebe que se muestran los valores correctos de la capa de datos cloud_retail o de comercio electrónico.

Comprobar si hay errores en las etiquetas

Si algunos campos son incorrectos o faltan cuando previsualiza la etiqueta, normalmente también se devuelve un error, a menos que la etiqueta no se active.

Puede consultar la página Monitorización en la consola de búsqueda de comercio para ver si hay errores. En esta página se registran la mayoría de los errores, excepto los de sintaxis, que suelen aparecer solo en los resultados de las solicitudes.

Puede seguir estos pasos para usar Chrome DevTools y comprobar si se han generado errores, incluidos los errores de sintaxis.

Activa el modo de vista previa en Tag Manager para tu sitio en un navegador Chrome y visita cualquier página en la que se deba activar la etiqueta Cloud Retail.
Con el modo de vista previa abierto, abre DevTools y haz clic en la pestaña Red.
Vuelve a cargar la página.
En DevTools, busca userEvent.

En la pestaña Red se muestra el evento userEvent:collect y su código de estado.
- Una respuesta 200 indica que tu etiqueta está en buen estado.
- Otras respuestas, como un error 400 y el evento destacado en rojo, indican que es necesario depurar.
Haz doble clic en el nombre del evento para ejecutar la solicitud y mostrar una respuesta completa con más información sobre el error.

Por ejemplo, puede que veas un error 400 que contenga el mensaje "'visitorId' is required, and cannot be empty", que indica que visitorId no se ha definido correctamente.
Si no se activa ningún userEvent, compruebe si hay errores de sintaxis en la capa de datos en la pestaña Consola de DevTools.

Registrar eventos de usuario con el etiquetado del lado del servidor

El etiquetado del lado del servidor le permite desplegar un único contenedor del lado del servidor con muchos clientes posteriores. De esta forma, se crea una única fuente de información veraz en el lado del cliente, con muchos consumidores del lado del servidor. Esta arquitectura traslada la carga de la web al servidor, por lo que es ideal para los usuarios que quieren maximizar el rendimiento de sus sitios web.

Otra ventaja del etiquetado del lado del servidor es que una sola etiqueta del lado del servidor también puede admitir muchos clientes upstream, como la Web y los móviles. Consulte cómo configurar el etiquetado del lado del servidor.

Vertex AI Search para el sector del comercio proporciona su propia etiqueta de servidor antigua.

La etiqueta del lado del servidor de Cloud Retail requiere y acepta parámetros similares a los de la etiqueta web de Cloud Retail, como los siguientes:

Número de proyecto
Clave de API (para la autenticación)
Sustituciones de campos clave, como visitorId y searchQuery

La diferencia principal entre la versión de servidor y la versión web de la etiqueta Cloud Retail es que no puedes definir la fuente de datos. La fuente de datos de las etiquetas de servidor es un flujo de datos enviado desde la etiqueta de Google en el esquema de GA4.

Configurar la etiqueta de Cloud Retail

Ver eventos registrados

Consulte las métricas de integración de eventos en la pestaña Eventos de la página Datos de la consola de búsqueda de comercio. En esta página se muestran todos los eventos escritos o importados en el último año. Las métricas pueden tardar hasta 24 horas en aparecer después de que se hayan insertado los datos correctamente.

Ir a la página Datos

Siguientes pasos

Más información sobre los eventos de usuario
También puede importar el historial de eventos de usuario. Puede que se tarde bastante en registrar suficientes datos de eventos de usuario para entrenar los modelos. Puede acelerar el entrenamiento inicial del modelo importando en bloque datos de eventos de usuario de eventos anteriores. Consulta Importar historial de eventos de usuario.
Vuelve a enviar los eventos si se registraron antes de que se completara la importación del catálogo.
Consulte información sobre cómo importar y gestionar eventos de usuario.
Empieza a recibir predicciones.
Monitorice y solucione problemas de los procesos de subida de datos.
Más información sobre Tag Manager