Importar historial de eventos de usuario

En esta página se describe cómo importar en bloque datos de eventos de usuario de eventos anteriores en Vertex AI Search para el sector del comercio. Se necesitan datos de eventos de usuario para entrenar los modelos. Después de configurar la grabación de eventos en tiempo real, puede tardar bastante en registrar suficientes datos de eventos de usuario para entrenar sus modelos. Importar el historial de datos puede acelerar el proceso.

Los procedimientos de importación que se describen en esta página se aplican tanto a las recomendaciones como a las búsquedas. Una vez que hayas importado los datos, ambos servicios podrán usar esos eventos, por lo que no tendrás que importar los mismos datos dos veces si usas ambos servicios.

Puedes importar eventos desde:

• Cloud Storage.
• BigQuery.
• BigQuery para eventos de Google Analytics 360.
• BigQuery para eventos de Google Analytics 4.
• Eventos insertados mediante el método userEvents.import.

Consejos generales para empezar

• Verifique que los datos se hayan importado por completo de Google Analytics 4 a BigQuery.
• Consulta el estado de la importación en la consola y consulta los datos de depuración o de error para solucionar problemas.
• Antes de importar el historial de datos de eventos de usuario, consulta las prácticas recomendadas para registrar eventos de usuario y la sección Antes de empezar de esta página.
• Importar datos históricos del catálogo puede mejorar aún más los eventos de usuario y la precisión del modelo.

Tutoriales

En estos tutoriales se muestra cómo importar eventos de usuario de varias fuentes.

Importar eventos de Cloud Storage

En este tutorial se explica cómo importar eventos de usuario de Cloud Storage.

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

Guíame

Importar eventos de BigQuery

En este tutorial se explica cómo importar eventos de usuario de BigQuery.

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

Guíame

Importar eventos insertados

En este tutorial se explica cómo importar datos de eventos de usuario de forma insertada.

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

Guíame

Antes de empezar

Para evitar errores de importación y verificar que hay suficientes datos para generar buenos resultados, revise la siguiente información antes de importar sus eventos de usuario.

• Consulta las prácticas recomendadas para registrar eventos de usuario.

• El formato de los eventos de usuario varía en función del tipo de evento de usuario. Consulte el esquema de tipos de eventos de usuario y ejemplos para ver el formato que debe especificar al crear tablas para cada tipo de evento.

• Las recomendaciones y las búsquedas tienen requisitos de datos mínimos diferentes. Asegúrate de que tus eventos de usuario cumplan los requisitos del servicio que quieras usar:

  • Consulta los requisitos y las prácticas recomendadas de los eventos de usuario para ver los requisitos de búsqueda y recomendaciones.

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

Consideraciones sobre la importación de eventos

En esta sección se describen los métodos que se pueden usar para importar por lotes los eventos de usuario históricos, cuándo se puede usar cada método y algunas de sus limitaciones.

Limitaciones de tamaño

El límite total del sistema es de 40.000 millones de eventos de usuario. Estos son los límites de tamaño de las importaciones de datos según la plataforma de ingestión:

• Para la importación en bloque desde Cloud Storage, cada archivo debe tener un tamaño de 2 GB o menos, y puedes incluir hasta 100 archivos en una sola solicitud de importación en bloque.

• En el caso de las importaciones de BigQuery, el límite de tamaño es de 128 GB.

• En el caso de las importaciones insertadas, se recomienda un máximo de 10.000 eventos de usuario por solicitud.

Para saber el número mínimo de días que se necesitan para registrar eventos de usuario en directo o importar eventos de usuario históricos para entrenar modelos y optimizar la búsqueda, consulta lo siguiente:

• Entrenamiento y ajuste generales del modelo: el entrenamiento y el ajuste iniciales del modelo suelen tardar entre 2 y 5 días en completarse, aunque puede llevar más tiempo en el caso de conjuntos de datos más grandes.

Optimización de la búsqueda

Para optimizar la experiencia de búsqueda en función de los eventos insertados, se necesitan al menos 250.000 eventos de búsqueda en los últimos 90 días.

• Para optimizar los resultados de búsqueda mediante eventos de usuario, se necesitan 500.000 eventos de vista de página de detalles atribuibles a un evento de búsqueda en los últimos 30 días.

• Se requiere una media de 10 eventos de vista de página de detalles atribuibles a un evento de búsqueda por producto en los últimos 30 días, a menos que se suban eventos de los últimos 21 días.

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

Importar eventos de usuario desde Cloud Storage

Importa eventos de usuario de Cloud Storage mediante la Google Cloud consola o el método userEvents.import.

Importar eventos de usuario de BigQuery

Importa eventos de usuario de BigQuery mediante la Google Cloud consola o el método userEvents.import.

Configurar el acceso a BigQuery

Sigue las instrucciones de Configurar el acceso a tu conjunto de datos de BigQuery para asignar a la cuenta de servicio de Vertex AI Search for commerce el rol mínimo Usuario de BigQuery necesario para que la importación se realice correctamente y el rol adicional Editor de datos de BigQuery para tu conjunto de datos de BigQuery. El rol Propietario de datos de BigQuery no es necesario.

Importar eventos de usuario de BigQuery

Puede importar eventos de usuario mediante la consola de búsqueda de comercio o el método userEvents.import.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
-v \
-X POST \
-H "Content-Type: application/json; charset=utf-8" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \
--data '{
  "inputConfig": {
    "bigQuerySource": {
      "datasetId": "DATASET_ID",
      "tableId": "TABLE_ID",
      "dataSchema": "SCHEMA_TYPE"
  }
}
}'

Importar eventos de usuario de Analytics 360 con BigQuery

Puede importar eventos de usuario de Analytics 360 si ha integrado Analytics 360 con BigQuery y usa Comercio electrónico mejorado.

En los siguientes procedimientos se da por hecho que ya sabes cómo usar BigQuery y Analytics 360.

Antes de empezar

Antes de empezar con los pasos siguientes, asegúrate de lo siguiente:

• Estás usando Comercio electrónico mejorado.
• Tiene BigQuery vinculado a Analytics 360.

Comprobar la fuente de datos

1. Asegúrate de que los datos de eventos de usuario que vas a importar tengan el formato correcto en una tabla de BigQuery a la que tengas acceso.

   Asegúrate de que la tabla se llame project_id:ga360_export_dataset.ga_sessions_YYYYMMDD.

   Consulte la documentación de Google Analytics para obtener más información sobre el formato y los nombres de las tablas.

2. En la consola de BigQuery Google Cloud , selecciona la tabla en el panel Explorador para verla.

   Comprueba que:

   1. La columna clientId tiene un valor válido, como 123456789.123456789.

      Ten en cuenta que este valor es diferente del valor completo de la cookie _ga (que tiene un formato como GA1.3.123456789.123456789).

   2. La columna hits.transaction.currencyCode tiene un código de moneda válido.

   3. Si tiene previsto importar eventos search, compruebe que haya una columna hits.page.searchKeyword o hits.customVariable.searchQuery.

      Aunque Vertex AI Search for commerce requiere tanto searchQuery como productDetails para devolver una lista de resultados de búsqueda, Analytics 360 no almacena las consultas de búsqueda y las impresiones de producto en un mismo evento. Para que Vertex AI Search for commerce funcione, debe crear una etiqueta en la capa de datos o un píxel de JavaScript para poder importar ambos tipos de eventos de usuario de fuentes de Google Analytics:

      • searchQuery, que se lee del parámetro search_term o de los eventos view_search_results, se deriva de hits.page.searchKeyword o de hits.customVariables.customVarValue si hits.customVariables.customVarName es searchQuery.
      • productDetails, la impresión del producto que se lee del parámetro items del evento view_item_list, se toma de hits.product si hits.product.isImpressions es TRUE.

3. Compruebe la coherencia de los IDs de los artículos entre el catálogo subido y la tabla de eventos de usuario de Analytics 360.

   Con cualquier ID de producto de la columna hits.product.productSKU de la vista previa de la tabla de BigQuery, usa el método product.get para asegurarte de que el mismo producto esté en tu catálogo subido.

   export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
   
      curl \
        -v \
        -X GET \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

Importar eventos de Analytics 360

Puede importar eventos de Google Analytics 360 mediante la consola de búsqueda de comercio o el método userEvents.import.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \\
  -v \\
  -X POST \\
  -H "Content-Type: application/json; charset=utf-8" \\
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

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

  return operationName;
}

Importar las vistas de página principal de Analytics 360 con BigQuery

En Analytics 360, los eventos de vista de página principal no se distinguen de otros eventos de vista de página. Esto significa que los eventos de vista de página principal no se importan como eventos con los otros tipos de eventos (como los de vista de página de detalles) en Importar eventos de Analytics 360.

En el siguiente procedimiento se explica cómo puede extraer eventos de vista de página principal de sus datos de Analytics 360 e importarlos a Vertex AI Search para el comercio. En resumen, esto se hace extrayendo las vistas de los usuarios de la página principal (identificadas por la ruta de la página principal) en una nueva tabla de BigQuery y, a continuación, importando datos de esa nueva tabla a Vertex AI Search para el comercio.

Para importar eventos de vista de página principal de Analytics 360 a Vertex AI Search para el comercio, siga estos pasos:

1. Crea un conjunto de datos de BigQuery o asegúrate de tener uno disponible al que puedas añadir una tabla.

   Este conjunto de datos puede estar en tu proyecto de Vertex AI Search para el sector del comercio o en el proyecto en el que tengas tus datos de Analytics 360. Es el conjunto de datos de destino en el que copiará los eventos de vista de la página principal de Analytics 360.

2. Crea una tabla de BigQuery en el conjunto de datos de la siguiente manera:

   1. Sustituye las variables del siguiente código SQL de la forma que se indica.

      • target_project_id: el proyecto en el que se encuentra el conjunto de datos del paso 1.

      • target_dataset: el nombre del conjunto de datos del paso 1.

      CREATE TABLE TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage (
       eventType STRING NOT NULL,
       visitorId STRING NOT NULL,
       userId STRING,
       eventTime STRING NOT NULL
      );

   2. Copia el código de ejemplo de SQL.

   3. Abre la página de BigQuery en la Google Cloud consola.

      Ir a la página de BigQuery

   4. Si aún no lo has hecho, selecciona el proyecto de destino.

   5. En el panel Editor, pega el código de ejemplo de SQL.

   6. Haz clic en play_circle Ejecutar y espera a que se complete la consulta.

   Al ejecutar este código, se crea una tabla con el formato target_project_id:target_dataset.ga_homepage_YYYYMMDD—por ejemplo, my-project:view_events.ga_homepage_20230115.

3. Copie los eventos de vista de página principal de Analytics 360 de su tabla de datos de Analytics 360 en la tabla que ha creado en el paso 2 anterior.

   1. Sustituye las variables del siguiente código de ejemplo de SQL de la siguiente manera:

      • source_project_id: el ID del proyecto que contiene los datos de Analytics 360 en una tabla de BigQuery.

      • source_dataset: el conjunto de datos del proyecto de origen que contiene los datos de Analytics 360 en una tabla de BigQuery.

      • source_table: la tabla del proyecto de origen que contiene los datos de Analytics 360.

      • target_project_id: el mismo ID de proyecto de destino que en el paso 2 anterior.

      • target_dataset: el mismo conjunto de datos de destino que en el paso 2 anterior.

      • Ruta: es la ruta a la página principal. Normalmente, es /. Por ejemplo, si la página principal es example.com/. Sin embargo, si la página principal es como examplepetstore.com/index.html, la ruta es /index.html.

      INSERT INTO `TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage(eventType,visitorId,userID,eventTime)`
      
      SELECT
        "home-page-view" as eventType,
        clientId as visitorId,
        userId,
        CAST(FORMAT_TIMESTAMP("%Y-%m-%dT%H:%M:%SZ",TIMESTAMP_SECONDS(visitStartTime)) as STRING) AS eventTime
      
      FROM
        `SOURCE_PROJECT_ID.SOURCE_DATASET.SOURCE_TABLE`, UNNEST(hits) as hits
      
      WHERE hits.page.pagePath = "PATH" AND visitorId is NOT NULL;

   2. Copia el código de ejemplo de SQL.

   3. Abre la página de BigQuery en la Google Cloud consola.

      Ir a la página de BigQuery

   4. Si aún no lo has hecho, selecciona el proyecto de destino.

   5. En el panel Editor, pega el código de ejemplo de SQL.

   6. Haz clic en play_circle Ejecutar y espera a que se complete la consulta.

4. Sigue las instrucciones que se indican en el artículo Importar eventos de usuario desde BigQuery para importar los eventos home-page-view de la tabla de destino. Durante la selección del esquema, si importa datos mediante la consola, seleccione Esquema de eventos de usuario de Retail. Si lo hace mediante userEvents.import, especifique user_event en el valor de dataSchema.

5. Elimina la tabla y el conjunto de datos que has creado en los pasos 1 y 2.

Importar eventos de usuario de Google Analytics 4 con BigQuery

Puede importar eventos de usuario de Google Analytics 4 si ha integrado Google Analytics 4 con BigQuery y usa el comercio electrónico de Google Analytics.

En los siguientes procedimientos se da por hecho que ya sabes cómo usar BigQuery y Google Analytics 4.

Antes de empezar

Antes de empezar con los pasos siguientes, asegúrate de lo siguiente:

• Usa la función Comercio electrónico de Google Analytics.
• Tiene BigQuery vinculado a Google Analytics 4.

Comprobar la fuente de datos

Para asegurarse de que los datos de eventos de usuario están preparados para la importación, siga estos pasos.

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.

1. Asegúrate de que los datos de eventos de usuario que vas a importar tengan el formato correcto en una tabla de BigQuery a la que tengas acceso.

   • El conjunto de datos debe llamarse analytics_PROPERTY_ID.
   • La tabla debe llamarse events_YYYYMMDD.

   Para obtener información sobre los nombres y el formato de las tablas, consulte la documentación de Google Analytics.

2. En la consola de BigQuery Google Cloud , selecciona el conjunto de datos en el panel Explorador y busca la tabla de eventos de usuario que quieras importar.

   Comprueba que:

   1. La columna event_params.key tiene una clave currency y su valor de cadena asociado es un código de moneda válido.

   2. Si tiene previsto importar eventos search, compruebe que la columna event.event_params.key tiene una clave search_term y un valor asociado.

      Aunque Vertex AI Search para comercio requiere tanto searchQuery como productDetails para devolver una lista de resultados de búsqueda, Google Analytics 4 no almacena las consultas de búsqueda y las impresiones de producto en un mismo evento. Para que Vertex AI Search para el comercio funcione, debe crear una etiqueta en la capa de datos o desde un píxel de JavaScript para poder importar ambos tipos de eventos de usuario de fuentes de Google Analytics:

      • searchQuery, que se lee del parámetro search_term o de los eventos view_search_results.
      • productDetails, la impresión del producto que se lee del parámetro items del evento view_item_list.

      Para obtener información sobre search en Google Analytics 4, consulte search en la documentación de Google Analytics.

3. Compruebe que los IDs de artículo del catálogo subido y de la tabla de eventos de usuario de Google Analytics 4 sean coherentes.

   Para comprobar que un producto de la tabla de usuarios de Google Analytics 4 también está en el catálogo que ha subido, copie un ID de producto de la columna event.items.item_id de la vista previa de la tabla de BigQuery y use el método product.get para comprobar si ese ID de producto está en el catálogo que ha subido.

   export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
   
      curl \
        -v \
        -X GET \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

Importar eventos de Google Analytics 4

Puede importar eventos de Google Analytics 4 mediante la consola de búsqueda de comercio o el método userEvents.import.

Usar la consola

1. Ve a la página Datos de la consola de búsqueda de comercio.
   
   Ir a la página Datos
2. Haga clic en Importar para abrir el panel Importar datos.
3. Elige Eventos de usuario.
4. Selecciona BigQuery como fuente de datos.

5. Seleccione el esquema de datos.

   • Google Analytics 4: se usa para los eventos de Google Analytics 4.
   • Google Analytics 360: úselo para los eventos de Google Analytics 360, a menos que solo importe eventos de vistas de la página principal de Google Analytics 360 (en ese caso, use el esquema de eventos de usuario de comercio).
   • Esquema de eventos de usuario de comercio: se usa para importar eventos de fuentes distintas de Google Analytics y para importar solo eventos de vistas de la página principal de Google Analytics 360.
6. Introduzca la tabla de BigQuery en la que se encuentran sus datos.
7. Opcional: Introduce la ubicación de un segmento de Cloud Storage de tu proyecto como ubicación temporal de tus datos.
   Si no se especifica ninguna, se usará una ubicación predeterminada. Si se especifica uno, el segmento de BigQuery y el de Cloud Storage deberán estar en la misma región.
8. Opcional: En Mostrar opciones avanzadas, introduce la ubicación de un segmento de Cloud Storage de tu proyecto como ubicación temporal de tus datos.
   
   Si no se especifica, se usa una ubicación predeterminada. Si se especifica uno, el segmento de BigQuery y el de Cloud Storage deberán estar en la misma región.
9. Haz clic en Importar.

Restringir la pertenencia a un grupo con la API

Importa tus eventos de usuario incluyendo los datos de los eventos en tu llamada al método userEvents.import. Consulta la referencia de la API userEvents.import.

En dataSchema, usa el valor user_event_ga4.

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
curl \\
  -v \\
  -X POST \\
  -H "Content-Type: application/json; charset=utf-8" \\
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event_ga4"
    }
  }
}'

Importar eventos de usuario de forma insertada

Puede importar eventos de usuario insertando los datos de los eventos en la llamada al método userEvents.import.

La forma más sencilla de hacerlo es incluir los datos de eventos de usuario en un archivo JSON y proporcionar el archivo a curl.

Para ver los formatos de los tipos de eventos de usuario, consulte Acerca de los eventos de usuario.

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

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

  return operationName;
}

Historial de datos de catálogo

También puede importar datos de catálogo que aparezcan en su historial de eventos de usuario. Estos datos del catálogo pueden ser útiles porque la información de productos anteriores se puede usar para enriquecer la captura de eventos de usuario, lo que a su vez puede mejorar la precisión del modelo.

Para obtener más información, consulta Importar datos históricos del catálogo.

Ver eventos importados

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

Evaluación de pruebas A/B

En función del objetivo de la prueba, se aplican los siguientes parámetros de la prueba A/B:

• Para conseguir el objetivo de tasa de clics (CTR), se necesitan al menos 21 días de eventos de usuario o volúmenes de eventos específicos. Por ejemplo, más de 2 millones de eventos de búsqueda y más de 500.000 clics en búsquedas.

• Para definir un objetivo de tasa de conversión o de ingresos, se necesitan al menos 28 días de eventos de usuario o volúmenes de eventos específicos. Por ejemplo, más de 4 millones de eventos de búsqueda, más de 1 millón de clics de búsqueda y más de 0, 5 eventos de compra por producto que se puede buscar.

Consulta la página Pruebas A/B para obtener más información sobre las pruebas A/B y las prácticas recomendadas.

Siguientes pasos

• Empieza a registrar eventos de usuario.
• Gestiona tus eventos de usuario.