Registra 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 venta minorista usa eventos de usuario en tiempo real para generar recomendaciones y resultados de la búsqueda. Registrar todos los tipos de eventos de usuario posibles con información válida del producto aumenta la calidad de tus resultados.

Los procedimientos de grabación de esta página se aplican a las recomendaciones y a la búsqueda. Después de registrar los datos, ambos servicios pueden usar esos eventos, por lo que no es necesario subir los mismos datos dos veces si usas ambos servicios.

Si deseas obtener detalles sobre los eventos de usuario, incluidos los tipos de eventos de usuario y el JSON de muestra para todos los tipos, consulta Acerca de los eventos de usuario.

Puedes registrar un evento de usuario de varias maneras:

Puedes encontrar ejemplos de la grabación de eventos del usuario de tipo detail-page-view para todos estos métodos a continuación. Para otros tipos de eventos, consulta Acerca de los eventos de usuario.

También puedes importar eventos históricos de los usuarios. Puede tardar bastante tiempo en registrar suficientes datos de eventos de usuario para entrenar tus modelos. Puedes acelerar el entrenamiento inicial de los modelos mediante la importación masiva de datos de eventos de usuario de eventos pasados. Consulta Cómo importar eventos históricos de usuarios.

Si el evento de usuario que registras es la primera interacción de un usuario con un producto basado en una recomendación o los resultados de la búsqueda proporcionados anteriormente, incluir un token de atribución permite que la API de venta minorista proporcione métricas de rendimiento. Para que funcione Vertex AI Search para la venta minorista, es necesario incluir un token de atribución. Para obtener información sobre cómo trabajar con tokens de atribución, consulta Tokens de atribución.

Los IDs de visitante son obligatorios cuando se registran eventos del usuario. Para obtener información sobre los IDs de visitante y usuario, consulta Acerca de la información del usuario.

Registra eventos de usuario con el etiquetado del servidor

El etiquetado del servidor te permite implementar un solo contenedor del servidor con muchos clientes descendentes. Esto crea una única fuente de información confiable en el cliente, con muchos consumidores del servidor. Esta arquitectura traslada la carga de la Web al servidor, lo que es conveniente para los usuarios que desean maximizar el rendimiento de sus sitios web.

La otra ventaja del etiquetado del servidor es que una sola etiqueta del servidor también puede admitir muchos clientes upstream, por ejemplo, web y para dispositivos móviles. Obtén más información para configurar el etiquetado del servidor.

Vertex AI Search para la venta minorista proporciona su propia etiqueta nativa del servidor.

La etiqueta 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 del proyecto
  • Clave de API (para la autenticación)
  • Anulaciones para campos clave, como visitorId y searchQuery

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

Configura la etiqueta de Cloud Retail

Instructivo para escribir eventos de usuario

En este instructivo, se muestra cómo registrar eventos de usuario con el método userEvents.write.

Para seguir la guía paso a paso sobre esta tarea directamente en el editor de Cloud Shell, haz clic en Guiarme:

GUIARME

Antes de comenzar

Antes de grabar eventos del usuario, debes asegurarte de:

  • Que se haya creado un proyecto de Google Cloud con la autenticación configurada.

  • Tener una clave de API válida (para JavaScript, Pixel o Tag Manager) o una cuenta de servicio válida con la función de editor de venta minorista asignada si se usa la API para escribir directamente.

    Para obtener más información, consulta Antes de comenzar.

Prácticas recomendadas para grabar eventos de usuarios

Vertex AI Search para venta minorista 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 ve afectada.

Cuando registres los eventos de los usuarios, asegúrate de implementar las siguientes prácticas recomendadas:

  • Si registras eventos de usuarios antes o durante la importación de tu catálogo, vuelve a unirte a cualquier evento registrado antes de que se complete la importación del catálogo.

    Puedes importar el catálogo antes, después o al mismo tiempo que registras los eventos del usuario. Hacer estas tareas en paralelo puede ahorrar tiempo si el catálogo es grande y hay muchos eventos del usuario. Una vez que se complete la importación del catálogo, debes usar la API para volver a unirte a los eventos que se subieron antes de que se complete la importación.

    Vertex AI Search para venta minorista intenta unir los eventos de usuario grabados con los metadatos del catálogo de productos cuando se crea el evento de usuario. Solo se usan con éxito los eventos unidos para el entrenamiento, así que asegúrate de volver a unirte a cualquier evento registrado antes de que el catálogo se haya importado por completo. Si un evento se refiere a un elemento que no existe en el catálogo, se descarta o no está asociado con los productos correctos. Del mismo modo, si importas eventos de usuario anteriores, el catálogo debe incluir los productos a los que hagan referencia. Puedes marcar los productos más antiguos como OUT_OF_STOCK en lugar de quitarlos del catálogo.

  • Mantén tu catálogo actualizado.

    Cuando registras eventos de usuarios, el producto incluido en el evento de usuario se conecta con el catálogo actual. Si registras un evento para un producto que no está en el catálogo actual, no se puede usar para entrenar tus modelos. Esto se denomina evento “no unido”. Si registraste eventos antes de que se importara tu catálogo por completo, debes volver a unirte a los eventos que se registraron durante la importación. Se espera que haya algunos eventos no unidos. Sin embargo, si el porcentaje de eventos no unidos alcanza el 5% o más de los eventos de tu usuario total, asegúrate de que tu catálogo esté actualizado, vuelve a unirte a los eventos que se registraron antes de que se actualice el catálogo por completo e investiga por qué se crean los eventos no unidos.

    Para ver tus eventos no unidos, usa el filtrado de eventos. Más información

  • Proporciona la mayor cantidad de información posible con tus eventos de usuario.

    Se necesita y acepta diferente información para cada tipo de evento de usuario. Para obtener más información, consulta Acerca de los eventos de usuario.

  • Configura alertas de Cloud Monitoring para que sepas si los procesos de grabación de eventos del usuario experimentan interrupciones.

  • Para una importación masiva de eventos de usuario, limita el tamaño de los datos que importas.

    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 o menos. Puedes incluir un máximo de 100 archivos en una sola solicitud de importación. Un enfoque es importar solo los eventos de usuario para un día a la vez.

  • Después de una importación masiva, revisa tus informes de errores para asegurarte de que tus datos se hayan importado correctamente.

  • Cuando importes datos de eventos de usuarios, incluye una marca de tiempo precisa para cada evento de usuario y evita importar eventos de usuario secuenciales con marcas de tiempo idénticas.

    Proporciona la marca de tiempo en el campo eventTime con el formato especificado por RFC 3339.

  • Si importaste eventos de usuario que son incorrectos, comunícate con tu contacto de Vertex AI Search for Retail para obtener información sobre cómo corregir el problema.

  • Cuando sea posible, mantén los datos de eventos de usuario continuos.

    La brecha en los datos de eventos de los usuarios puede reducir la calidad del modelo.

  • Usa un formulario seguro de un identificador único para mantener a los usuarios anónimos en Vertex AI Search para la venta minorista y proteger la privacidad de los usuarios. Eres responsable de ocultar la PII (información de identificación personal), como el correo electrónico o las direcciones particulares, de tus datos.

Registra eventos de usuario con un píxel de JavaScript

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

<script type="text/javascript">
var user_event = {
  "eventType" : "detail-page-view",
  "visitorId": "visitor-id",
  "userInfo": {
      "userId": "user-id"
  },
  "attributionToken": "attribution-token",
  "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 importaste eventos de usuario con Google Analytics 360, configura visitorID como el ID de cliente de Google Analytics. Ten en cuenta que el ID de cliente de Google Analytics es solo una parte del nombre completo de la cookie _ga (por ejemplo, el ID de cliente 123456789.123456789 es parte de la cookie _ga de GA1.3.123456789.123456789).

El siguiente es un ejemplo abreviado que muestra el formato para configurar el ID de cliente en un evento del usuario. Reemplaza “G-XXXXXX” por tu ID de seguimiento de Google Analytics.

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

Registra eventos de usuario con el método userEvents.write

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

Para registrar eventos de usuario, envía una solicitud POST al método userEvents.write y proporciona el cuerpo de la solicitud correspondiente.

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;
}

Registra eventos de usuarios con Google Analytics 4

Puedes registrar los datos de eventos de usuario de Google Analytics 4 en Vertex AI Search for Retail.

Verifica tu fuente de datos

Asegúrate de que los datos de eventos de usuario que deseas importar tengan el formato correcto.

Para ver una tabla de los campos de Google Analytics 4 que usa Vertex AI Search para la venta minorista y a qué campos de Vertex AI Search para la venta minorista se asignan, consulta Campos de eventos del usuario de Google Analytics 4.

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

Verifica lo siguiente:

  1. Si importas eventos de compra, que algunos modelos de Vertex AI Search para venta minorista requieren, tus informes de eventos incluyen códigos de moneda. Consulta los parámetros de eventos purchase en la documentación de Google Analytics.

  2. Si planeas importar eventos search, tus informes de eventos incluirán las búsquedas.

    Se admite la importación de eventos search, pero estos no se asignan desde Google Analytics 4 de la misma manera que otros tipos de eventos, ya que Google Analytics 4 no admite de forma nativa el tipo de evento search de la Búsqueda de Vertex AI para venta minorista.search Durante la importación, los eventos search se construyen a partir de Google Analytics 4 combinando la información de los parámetros de eventos view_item_list y search_term.

    Consulta los parámetros de eventos search en la documentación de Google Analytics.

Registra tus eventos de Google Analytics 4

Para registrar un evento de usuario, incluye datos JSON sin procesar codificados con URL para el evento en tu llamada al método userEvents.collect.

Para el parámetro prebuilt_rule, usa el valor ga4_bq.

Para facilitar la lectura, en el siguiente ejemplo del uso de la llamada userEvents.collect, primero se establece GA4_EVENT como una variable que contiene los datos JSON sin procesar de un evento de ejemplo. Luego, la llamada a userEvents.collect del ejemplo codifica los datos del evento con la URL mediante la variable GA4_EVENT.

  1. Para facilitar la codificación de URL más adelante, puedes establecer GA4_EVENT como una variable que contenga datos del evento. 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"
}'

  2. Realiza una llamada a userEvents.collect que incluya los datos JSON sin procesar codificados con 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'"

Registra eventos de usuario con Google Tag Manager

Tag Manager proporciona una forma de administrar y probar varias etiquetas sin muchos cambios de código del servidor en tu sitio.

Algunas decisiones que tomas durante la configuración dependen de si usas Google Analytics y el comercio electrónico de Google Analytics. El comercio electrónico de Google Analytics se puede implementar con Google Analytics 4 o el comercio electrónico mejorado. La etiqueta de Cloud Retail admite ambas opciones.

No se requieren Google Analytics ni Google Analytics Comercio electrónico. Si no los usas, puedes configurar Variable: Comercio electrónico cuando crees la etiqueta de venta minorista de Cloud, o bien propagar de forma manual el código de la capa de datos de tu sitio después de crear la etiqueta.

El comercio electrónico de Google Analytics es una configuración adicional para Google Analytics que pasa títulos de productos, IDs, precios, detalles de transacciones y otros datos de comercio electrónico estructurados a Google Analytics. Vertex AI Search para venta minorista puede usar automáticamente la capa de datos de comercio electrónico de Google Analytics, por lo que si ya lo configuraste, la configuración puede ser más fácil. Si no tienes configurado el comercio electrónico de Google Analytics, pero deseas usarlo, consulta más detalles y las instrucciones de configuración en la Guía para desarrolladores de GA4.

Usa este procedimiento único para configurar una etiqueta de venta minorista de Cloud en Tag Manager para registrar eventos de usuario.

Crea una variable de ID de visitante

El valor visitorId es para realizar un seguimiento de los usuarios. Por lo general, visitorId es un ID de sesión y es obligatorio para todos los eventos. Configura una variable que establezca los ID de sesión como visitorId.

Si usas Google Analytics, puedes usar el ID de visitante de Google Analytics. Para configurar esto, usa el siguiente procedimiento para anular el valor del ID de visitante de la etiqueta de Cloud Retail. Esta acción asigna la cookie de origen “_ga” a una variable de Tag Manager llamada “GA visitorId”. Puedes hacer lo mismo con cualquier cookie de ID de sesión. No es necesario que sea de Google Analytics.

En este procedimiento, se supone que usas Google Analytics. Si no es el caso, puedes usar otra cookie o variable, o bien obtener el ID de visitante de la capa de datos cloud_retail.

Para establecer el valor visitorID en una variable para la etiqueta de venta minorista de Cloud, sigue estos pasos:

  1. En Tag Manager, ve a la pestaña Variables y haz clic en Nueva para crear una nueva variable definida por el usuario.

  2. Asigna un nombre a la variable en la parte superior del cuadro de diálogo, como "GA visitorId".

  3. Ingresa la configuración de la variable.

    Puedes usar el ID de cliente o el ID de cookie para establecerlos como la fuente de los IDs de visitante. Siempre usa una fuente de ID de visitante coherente cuando transfieras eventos históricos y en tiempo real de los usuarios.

    ID de cliente

    En Google Analytics 4, esta variable se asigna al campo user_pseudo_id en el esquema de BigQuery Export de Google Analytics 4.

    1. Configura el Tipo de variable como JavaScript personalizado.

    2. Ingresa la siguiente secuencia de comandos en el campo JavaScript personalizado.

      Reemplaza “G-XXXXXX” por tu ID de seguimiento de Google Analytics. Para encontrar tu ID de seguimiento, consulta ¿Qué sucedió 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.

    1. Elige Cookie de primera mano como tipo de variable.

    2. En el campo Nombre de cookie, ingresa _ga.

    3. Haz clic en Valor de formato, selecciona Convertir no definido a… y, luego, ingresa "" (una string vacía).

    4. Haz clic en Guardar para guardar la variable.

      Esta acción asigna la cookie de origen “_ga” a una variable de Tag Manager llamada “GA visitorId”.

A continuación, crea una etiqueta de venta minorista de Cloud en Tag Manager. Esta etiqueta usará la variable de ID del visitante que acabas de crear.

Cómo crear una etiqueta de Google Tag Manager

Configura una etiqueta en Tag Manager para enviar información del evento del usuario a la búsqueda de Vertex AI para la venta minorista.

  1. Accede a Tag Manager y selecciona el contenedor de tu sitio.

  2. Ve a la pestaña Etiquetas y haz clic en Nueva para agregar una etiqueta nueva.

  3. Asigna un nombre a tu etiqueta en la parte superior del panel (el marcador de posición es Variable sin título), como "Búsqueda de Vertex AI para venta minorista".

  4. Haz clic en Configuración de la etiqueta y elige la etiqueta Cloud Retail para abrir el panel de configuración de la etiqueta.

  5. Ingresa tu clave de API.

    Usa la clave que creaste cuando configures Vertex AI Search para la venta minorista.

    Las claves de API están disponibles en la página APIs y servicios > Credenciales en la consola de Google Cloud.

  6. Ingresa el número del proyecto de Google Cloud en el que está habilitada la Búsqueda de Vertex AI para venta minorista.

    El número del proyecto está disponible en el panel de la consola de Google Cloud.

  7. En el campo Fuente de datos de eventos del usuario, haz lo siguiente:

    • Capa de datos (recomendado): Selecciona esta opción si tu implementación será una de las siguientes:

      • Tienes implementado el comercio electrónico de Google Analytics a través de Tag Manager. Reutiliza la capa de datos como fuente de datos de eventos en lugar de propagar una nueva. Esto usa el esquema de Google Analytics 4 si está presente. De lo contrario, se usa el comercio electrónico mejorado de UA. Con esta fuente de datos, solo puedes registrar eventos add-to-cart, purchase-complete, detail-page-view y search. Los eventos search se registran con impresiones de comercio electrónico combinadas con búsquedas (consulta Cómo crear una variable de búsqueda).

      • Estás usando el comercio electrónico de Google Analytics y puedes propagar de forma manual el código de la capa de datos. Consulta la Guía para desarrolladores de Tag Manager.

    • Variable: Venta minorista de Cloud: Selecciona esta opción para propagar una variable de Tag Manager con los campos obligatorios para Vertex AI Search para la venta minorista. Puedes elegir esta opción si no usas el comercio electrónico de Google Analytics o si el comercio electrónico de Google Analytics no tiene los datos necesarios para la Búsqueda de Vertex AI para la venta minorista. Si cambias a esta fuente desde la opción heredada de la capa de datos de venta minorista de Cloud, también crea una variable de capa de datos con la clave cloud_retail y asóciala con esta opción de variable de venta minorista de Cloud.

    • 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 propagar de forma manual el código de la capa de datos.

      En el campo Leer datos de comercio electrónico de variables de usuario que aparece, elige una variable. Esto permite que Vertex AI Search para venta minorista lea los datos de eventos del usuario de comercio electrónico de Google Analytics desde una variable personalizada que creas.

      La variable debe coincidir con el formato documentado en la Guía para desarrolladores de GA4. Para construir una variable con el formato correcto, puedes usar el Creador de objetos de comercio electrónico mejorado, una plantilla de variables personalizada de la Galería de plantillas de la comunidad de Tag Manager. Google no mantiene las plantillas de la comunidad. Para usar esta plantilla, consulta la página de la galería del Creador de objetos de comercio electrónico mejorado para obtener documentación y otros recursos.

  8. Haz clic en el botón + Reemplazar un valor en el mensaje UserEvent.

  9. En Selector de campos, selecciona visitorId como el campo y, en Valor del campo, selecciona la nueva variable de ID de visitante que creaste en Crear una variable de ID de visitante.

  10. Haz clic en Guardar.

    Se creó tu etiqueta de venta minorista de Cloud.

Opciones de fuentes de datos heredadas

Anteriormente, las opciones Capa de datos: Comercio electrónico y Capa de datos: Cloud Retail estaban disponibles como opciones de fuentes de datos. Estas opciones heredadas no están disponibles en las etiquetas nuevas. Si cambias una etiqueta existente a una fuente de datos nueva, obtén una vista previa con Tag Manager para verificarla antes de la implementación. Cuando cambies de cuenta, ocurrirá lo siguiente:

  • Si usaste Capa de datos: Comercio electrónico, puedes cambiar a Capa de datos. Si está presente, se usa el esquema de Google Analytics 4. De lo contrario, se usa el comercio electrónico mejorado de UA.

  • Si usaste Capa de datos: venta minorista de Cloud, cambia a la opción Variable: venta minorista de Cloud. Crea una variable de capa de datos con la clave cloud_retail y asóciala con la opción Variable: venta minorista de Cloud.

Siguiente:

Crea una variable de búsqueda

Si usas la búsqueda, puedes crear una variable en Tag Manager para las búsquedas y adjuntarla a tu etiqueta de venta minorista de Cloud. Esto permite que Vertex AI Search for Retail obtenga búsquedas de Analytics.

Los tipos de variables que creas dependen de tu fuente de datos de eventos del usuario.

  • Variable: Comercio electrónico o la capa de datos con el esquema de comercio electrónico de Google Analytics: Crea una variable de elemento de URL o DOM en Tag Manager y adjúntala a tu etiqueta de venta minorista de Cloud. Además, habilita la opción de que tu etiqueta use impresiones de comercio electrónico de Google Analytics para crear eventos de búsqueda.
  • Variable: venta minorista de Cloud o una capa de datos propagada de forma manual: Crea una variable de elemento de URL o DOM en Tag Manager y adjúntala a tu etiqueta de venta minorista de Cloud. Para determinar si el tipo de evento de un usuario es search, también debes hacer lo siguiente:
    • Crea una variable de tipo constante para los tipos de eventos de búsqueda y adjúntala a tu etiqueta.
    • Establece el tipo de evento de búsqueda en tu capa de datos o en la variable de venta minorista de Cloud.

Crea y adjunta una variable de Tag Manager para las búsquedas

Si usas la búsqueda, puedes crear una URL, un elemento DOM o una variable de JavaScript personalizada que se propagará con las búsquedas ingresadas en tu sitio.

Como alternativa a este procedimiento, puedes configurar la capa de datos para proporcionar información de búsqueda. Sin embargo, es posible que elijas usar variables de Tag Manager si no tienes acceso a la capa de datos o prefieres no configurar la capa de datos.

Puedes crear una variable de tipo de URL, una variable de tipo de elemento DOM o una variable de JavaScript (página) personalizada. La configuración que crees y la forma en que la configures dependerá de la implementación de tu sitio:

  • Una variable de URL obtiene búsquedas de las URL de resultados de búsqueda de tu sitio. Usa esta variable si tu sitio incluye la string de consulta en la URL de sus resultados de búsqueda.
  • Una variable de elemento DOM obtiene la información de búsqueda del modelo de objetos del documento (DOM) de tu sitio. No es necesario editar el DOM para usar esta variable. Sin embargo, deberías poder leer y comprender el DOM para configurar esta variable de manera correcta.
  • Una variable de JavaScript personalizado muestra datos con el formato de una función de JavaScript. Esto es útil si tienes datos existentes a los que deseas aplicar formato en el esquema de venta minorista o comercio electrónico de Cloud.

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

  1. En Tag Manager, ve a la pestaña Variables y haz clic en Nueva para crear una nueva variable definida por el usuario.

  2. Asigna un nombre a la variable en la parte superior del cuadro de diálogo, como "search_variable".

  3. Ingresa la configuración de la variable:

    Tipo de URL

    1. Configura el Tipo de variable como URL.

    2. Configura Tipo de componente como Consulta.

    3. Si especificas una clave de consulta, configúrala como la clave que precede a la búsqueda en tu 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 establecería como shoes.

    Tipo de elemento DOM

    1. Configura Tipo de variable como Elemento DOM.

    2. Configura el Método de selección y, luego, ingresa el ID o el selector de elementos de la búsqueda.

      Esta configuración depende de si tu sitio usa un ID de elemento o un selector de CSS para identificar la búsqueda.

    3. Si especificas un atributo, configúralo en el atributo que contiene el término de búsqueda.

      Por ejemplo, si la búsqueda en tu DOM es <id="search" value="shoes">, el atributo sería value. En este ejemplo, el valor de la variable se establecería como shoes.

    Tipo de JavaScript personalizado

    1. Configura el Tipo de variable como JavaScript personalizado.

    2. Reemplaza las variables en el siguiente código y pégalo en el panel Custom JavaScript.

    3. En el panel Código JavaScript personalizado, agrega un código JavaScript que devuelva un evento de búsqueda en el esquema de venta minorista.

      En el siguiente código de muestra, se transforman los datos de una variable Ecommerce Items existente en el array productDetails que usa la Búsqueda de Vertex AI para el esquema de venta minorista y se muestra un evento completo. Para usar este código, reemplaza 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;
}

  4. Haz clic en Guardar para guardar la variable.

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

  1. En la página Tag Manager, en Etiquetas, haz clic en tu etiqueta de venta minorista de Cloud para editarla.

  2. Si la fuente de datos del evento de usuario de la etiqueta es Variable: Comercio electrónico o usas la capa de datos con el esquema de comercio electrónico de Google Analytics, selecciona la casilla de verificación Use impresiones de comercio electrónico mejoradas para crear eventos de búsqueda.

    Esto permite que Vertex AI Search for Retail determine si el tipo de evento de un usuario es search según los datos de búsqueda que obtiene de esta etiqueta.

  3. En la sección Datos de los eventos del usuario, haz clic en el botón + Reemplazar un valor en el mensaje UserEvent.

  4. Selecciona searchQuery en Selector de campos y establece la variable de búsqueda como Valor de campo.

  5. Guarda la etiqueta.

Siguiente:

Crea y adjunta una variable constante

Puedes usar este procedimiento si eliges Variable: venta minorista de Cloud o una capa de datos propagada de forma manual como la fuente del evento de usuario para tu etiqueta de venta minorista de Cloud.

Crear una variable de tipo constante para eventos de búsqueda y configurarla como una anulación del evento de usuario en tu etiqueta de venta minorista de Cloud permite que la Búsqueda de Vertex AI para venta minorista determine si el tipo de evento de usuario es search.

Como alternativa a este procedimiento, puedes especificar el tipo de evento de usuario search a través de la capa de datos o la variable de venta minorista de Cloud que usas como fuente de eventos de tu etiqueta. De lo contrario, sigue los pasos a continuación para configurar el tipo de evento.

Primero, crea una variable de tipo constante:

  1. En Tag Manager, ve a la pestaña Variables y haz clic en Nueva para crear una nueva variable definida por el usuario.

  2. Asigna un nombre a la variable en la parte superior del cuadro de diálogo, como "search_constant".

  3. Configura el Tipo de variable como Constante.

  4. Ingresa search en el campo Value (Valor).

  5. Haz clic en Guardar para guardar la variable.

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

  1. En la página Tag Manager, en Etiquetas, haz clic en tu etiqueta de venta minorista de Cloud para editarla.

  2. En la sección Datos de los eventos del usuario, haz clic en el botón + Reemplazar un valor en el mensaje UserEvent.

  3. Selecciona eventType en Selector de campos y establece la variable de búsqueda como Valor de campo.

  4. Guarda la etiqueta.

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

Crea activadores de eventos para tu etiqueta de Tag Manager

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

Las etiquetas de Tag Manager deben tener activadores que controlen cuándo se debe “activar” en el sitio. Los activadores detectan cuando ocurren eventos (como un usuario que ve la página principal o agrega un artículo a su carrito) y le solicita a tu etiqueta que envíe esa información del evento del usuario a la Búsqueda de Vertex AI para venta minorista.

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

Por lo general, configurarás la etiqueta para que se active cuando un usuario vea cualquier página que tenga los eventos necesarios para Vertex AI Search for Retail (como la página principal, las páginas de detalles de productos, las de carrito o la página de confirmación de la compra). En estos casos, la etiqueta debe activarse después de que se cargue la página, para que las cookies estén disponibles y se propaguen todas las variables de la capa de datos. Para lograrlo, configura los activadores a fin de que se activen en Window Loaded o DOM Ready.

Es posible que debas activar la etiqueta cuando se realice una acción en lugar de hacerlo cuando se cargue la página (por ejemplo, si un usuario que agrega un artículo a un carrito no fuerza la carga de una página). En estos casos, puedes configurar esa acción de clic en tu sitio para enviar actualizaciones de forma simultánea a la capa de datos y asociar el activador con esa acción.

Por ejemplo, si creaste un activador para eventos add-to-cart, puedes elegir el tipo de activador como Clic solo en vínculos: y configurarlo para que se active en el ID de clic (en este ejemplo, addtocart). Luego, debes configurar el vínculo addtocart en tu sitio para actualizar la capa de datos con valores nuevos cuando hagas clic:

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

Para algunos eventos de usuarios, debes crear un activador personalizado. En general, se crea un activador personalizado en Tag Manager con el nombre del evento del usuario. Si no puedes modificar el código de frontend, puedes crear un activador personalizado con las macros de JavaScript. Para obtener más información sobre los activadores personalizados, consulta Activador de eventos personalizados.

Usa los siguientes procedimientos para crear activadores en Tag Manager:

Crea activadores nuevos para tu etiqueta de Tag Manager

Si no usas el comercio electrónico de Google Analytics, crea activadores de eventos nuevos para cualquier evento de usuario que necesiten tus modelos de venta minorista de Vertex AI Search. Luego, asocia tus activadores nuevos con la etiqueta de venta minorista de Cloud que creaste en Tag Manager.

Antes de comenzar con los siguientes pasos, asegúrate de haber creado una etiqueta de venta minorista de Cloud en Tag Manager. Consulta Cómo crear una etiqueta de Tag Manager.

Primero, crea los activadores. Repite este procedimiento para todos los eventos de usuario que requieren tus modelos de Vertex AI Search for Retail:

  1. En la página Activadores de Tag Manager, haz clic enNueva > Configuración del activador.

  2. Elige el tipo de activador que se aplicará al evento del usuario para el que creas un activador.

  3. Guarda el activador.

A continuación, asocia tus activadores nuevos a tu etiqueta de venta minorista de Cloud. Este es un procedimiento único:

  1. En la página Tag Manager, en Etiquetas, haz clic en tu etiqueta de venta minorista de Cloud para editarla.

  2. Haz clic en Activador, selecciona tus activadores nuevos y haz clic en Agregar.

  3. Guarda la etiqueta.

A continuación, obtén una vista previa de la etiqueta y configura la supervisión de los errores de grabación de eventos y otros problemas para asegurarte de que los datos se sigan recibiendo correctamente.

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

Cómo volver a usar los activadores de comercio electrónico de Google Analytics

Si implementaste el comercio electrónico de Google Analytics mediante Tag Manager, vuelve a usar los activadores de eventos de tu comercio electrónico de Google Analytics para la Búsqueda de Vertex AI para la venta minorista.

Con esta fuente de datos, solo puedes registrar eventos add-to-cart, purchase-complete, detail-page-view y search. Los eventos search se registran con impresiones de comercio electrónico combinadas con búsquedas (consulta Cómo crear una variable de búsqueda).

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

Google Analytics 4 Comercio electrónico mejorado Vertex AI Search para la venta minorista
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 comenzar con estos pasos, asegúrate de haber hecho lo siguiente:

  • Configuraste una etiqueta en Tag Manager del tipo de etiqueta Google Analytics: Evento de GA4 y habilitaste el comercio electrónico mejorado o GA4 en ella. Consulta la documentación de Tag Manager y la Guía para desarrolladores de GA4 para obtener más detalles.
  • Configuraste tu etiqueta de Comercio electrónico mejorado o GA4 en Tag Manager para que se active en los eventos de usuario que planeas registrar para Vertex AI Search for Retail.
  • Creaste una etiqueta de venta minorista de Cloud en Tag Manager, con "Capa de datos" o "Variable: comercio electrónico" como la fuente de datos de eventos del usuario (consulta Cómo crear una etiqueta de Tag Manager).

Para volver a usar los activadores de comercio electrónico de Google Analytics, haz lo siguiente:

  1. En la página Etiquetas de Tag Manager, haz clic en tu etiqueta de comercio electrónico de Google Analytics (tipo Google Analytics: Evento de GA4) para editarlo.

  2. En Configuración avanzada > Secuenciación de etiquetas, selecciona Activa una etiqueta después <nombre de la etiqueta de comercio electrónico mejorado o GA4> activaciones.

  3. Selecciona tu etiqueta de venta minorista de Cloud como Etiqueta de limpieza.

    Selecciona No activar <nombre de la etiqueta de Cloud Retail> si el nombre de la etiqueta de comercio electrónico mejorado o de GA4 falla o se detiene.

  4. Guarda la etiqueta.

A continuación, obtén una vista previa de la etiqueta y configura la supervisión de los errores de grabación de eventos y otros problemas para asegurarte de que los datos se sigan recibiendo correctamente.

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

Usa la capa de datos cloud_retail con Tag Manager

Si creaste tu etiqueta de venta minorista de Cloud en Tag Manager para usar la capa de datos cloud_retail como la fuente del evento de usuario, configura la variable dataLayer en el HTML de origen como se describe en el artículo 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 según el usuario o la página (como los ID de usuario o de producto). Para la etiqueta de venta minorista de Cloud, esos datos deben exponerse de forma estructurada a través de una capa de datos para que Tag Manager pueda usarlos.

La capa de datos es un objeto de JavaScript que generalmente se agrega a una página mediante el código del servidor o el frontend mediante HTML o una plantilla. Si se configura una página con la capa de datos, contendrá un código como el 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 un elemento de arreglo.

Campos obligatorios en la capa de datos cloud_retail

En Acerca de los eventos de usuario, se enumeran todos los campos y ejemplos obligatorios para los tipos de eventos que se deben pasar a la capa de datos cloud_retail.

El código o las plantillas del servidor deben tener las etiquetas de secuencia de comandos correctas en cada página desde la que deseas enviar eventos. Después de que el objeto dataLayer se propaga correctamente en cada página, deberías poder probar la etiqueta de venta minorista de Cloud.

Algunos campos como visitorId son obligatorios para el mensaje UserEvent, pero pueden no estar disponibles cuando se propaga la capa de datos. Por ejemplo, visitorId podría derivar de la cookie del usuario o experimentIds del framework de experimentación A/B. En este caso, usa una variable para reemplazar el campo de la etiqueta de Tag Manager.

Puedes reemplazar los siguientes campos:

  • visitorId
  • userInfo.userId
  • attributionToken
  • experimentIds

Para obtener información sobre cómo reemplazar un campo UserEvent en Tag Manager, consulta Configuración del campo visitorID en Tag Manager, que explica cómo reemplazar el valor del campo visitorId. por una variable definida por el usuario.

En el siguiente ejemplo, se muestra la capa de datos que se debe incluir en la página para un UserEvent detail-page-view mediante 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'
      },
      'attributionToken': 'attribution-token',
      // 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>

Obtén una vista previa de tu etiqueta de Tag Manager

El modo de vista previa de Tag Manager te permite probar etiquetas nuevas antes de publicarlas en tu sitio en vivo.

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

Usa el siguiente procedimiento para confirmar que tu etiqueta se activa correctamente.

  1. En la página de descripción general de Tag Manager, haz clic en Vista previa.

    El modo de vista previa de Tag Manager se abre en una pestaña del navegador nueva.

  2. Ingresa la información del sitio y haz clic en Iniciar para iniciar Tag Assistant.

    En la pestaña actual del navegador, se inicia Tag Assistant y tu sitio se abre en una pestaña nueva.

  3. En su sitio, visite cualquier página en la que se deba activar la etiqueta de venta minorista de Cloud.

  4. Confirma que el asistente de etiquetas muestra la etiqueta de venta minorista de Cloud en la pestaña Etiquetas en la sección Etiquetas activadas.

  5. En Tag Assistant, ve a la pestaña Capa de datos y verifica que se muestren los valores correctos de la capa de datos cloud_retail o de comercio electrónico.

Cómo verificar si hay errores de etiquetas

Si algunos campos son incorrectos o no aparecen cuando obtienes una vista previa de la etiqueta, esta, por lo general, también muestra un error, a menos que no se active.

Puedes consultar la página Supervisión en la consola de Search for Retail 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.

Puedes usar los siguientes pasos a fin de usar herramientas para desarrolladores de Chrome para verificar si se generaron errores, incluidos los errores de sintaxis.

  1. Activa el modo de vista previa en Tag Manager para tu sitio en un navegador Chrome y visita cualquier página donde se deba activar la etiqueta de venta minorista de Cloud.

  2. Con el modo de vista previa abierto, abre Herramientas para desarrolladores y haz clic en la pestaña Red.

  3. Vuelve a cargar la página.

  4. En Herramientas para desarrolladores, busca userEvent.

    La pestaña Red 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 destacar el evento en rojo, indican que se requiere depuración.

  5. 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, es posible que veas un error 400 que contenga el mensaje "visitorId es obligatorio y no puede estar vacío", lo que indica que visitorId no se configuró correctamente.

  6. Si no se activa ningún userEvent, consulta la pestaña Consola de Herramientas para desarrolladores para detectar errores de sintaxis en la capa de datos.

Supervisa el estado de la importación

La grabación exitosa de los eventos de los usuarios es importante para obtener resultados de alta calidad. Debes supervisar las tasas de error de la grabación de eventos y tomar medidas si es necesario. Si quieres obtener más información, consulta Configuración de alertas para problemas de carga de datos.

Cómo ver los eventos grabados

Consulta las métricas de integración de eventos en la pestaña Eventos de la página Datos de la consola de Search for Retail. En esta página, se muestran todos los eventos que se escribieron o importaron en el último año. Las métricas pueden tardar hasta 24 horas en aparecer después de que se transfieren los datos correctamente.

Ir a la página Datos

¿Qué sigue?