Acerca de los eventos del usuario

En esta página, se describen los eventos de usuario para las apps de Gemini Enterprise, incluidos los tipos de eventos de usuario, los requisitos y los ejemplos para los tipos de eventos de usuario.

Si usas las APIs de Gemini Enterprise en tus propias apps, debes configurar la búsqueda en tu app para obtener los eventos de usuario y, luego, agregar los datos de eventos de usuario a tu app de Gemini Enterprise.

Si creas tu app a través de la Google Cloud consola, entonces no necesitas importar eventos de usuario de forma manual (y no necesitas leer esta página).

Para obtener ayuda con el registro de eventos de usuario, consulta Registra eventos de usuario en tiempo real. Para importar eventos de usuario anteriores de forma masiva, consulta Importa eventos de usuario históricos.

Tipos de eventos del usuario

Puedes registrar los siguientes tipos de eventos de usuario a medida que los usuarios finales exploran o buscan en tu sitio:

Nombre del evento del usuario Acción del usuario
view-item Muestra los detalles de un documento.
search Busca datos en la app de Gemini Enterprise.

Para obtener detalles sobre el objeto de evento de usuario, consulta la UserEvent documentación de referencia de la API.

Ejemplos y esquemas de los tipos de eventos del usuario

En esta sección, se proporcionan los formatos de datos para cada tipo de evento que admiten las apps de Gemini Enterprise. Se proporcionan ejemplos de JavaScript Pixel. En el caso de BigQuery, se proporciona el esquema de tabla completo para cada tipo.

Para todos los tipos de eventos de usuario, userId es opcional.

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

view-item

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

Requisitos de optimización de la búsqueda para eventos view-item

Para permitir que la búsqueda optimice automáticamente la experiencia de búsqueda en función de las tendencias generales de los usuarios, sube los siguientes datos.

Los eventos se deben subir al menos una vez al día con una demora máxima de 24 horas.

Métrica de eventos Volumen o frecuencia de eventos Descripción
Volumen de eventos view-item 250,000 elementos vistos

Se requieren al menos 250,000 elementos vistos para optimizar la experiencia de búsqueda en función de los eventos incorporados.

Objeto view-item mínimo requerido

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

El documents objeto contiene el ID del documento (id) y su nombre de recurso (name).

  • Cuando incorporas o registras eventos de usuario a nivel del almacén de datos, puedes proporcionar el ID del documento (id) o el nombre de recurso (name).
  • Cuando incorporas o registras eventos a nivel de la ubicación, debes proporcionar el nombre de recurso del documento (name), ya que indica la ruta completa de un documento y hace referencia al almacén de datos en el que reside el documento. Puedes proporcionar el ID del documento como información adicional opcional.

JavaScript Pixel

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "name": "DOCUMENT_NAME"
  }]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "userId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "userAgent",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageviewId",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "uri",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "referrerUri",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "tagIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "example_text_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          }
        ]
      },
      {
        "name": "example_number_attribute",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "numbers",
            "type": "NUMERIC",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  }
]

A continuación, se muestra el formato del evento de usuario search.

Requisitos de optimización de la búsqueda para eventos search

Para permitir que la búsqueda optimice automáticamente la experiencia de búsqueda en función de las tendencias generales de los usuarios, sube los siguientes datos.

Los eventos se deben subir al menos una vez al día con una demora máxima de 24 horas.

Métrica de eventos Volumen o frecuencia de eventos Descripción
Volumen de eventos search 100,000 búsquedas

Se requieren al menos 100,000 búsquedas para optimizar la experiencia de búsqueda en función de los eventos incorporados.

Objeto search mínimo requerido

En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario search.

Proporciona searchQuery para los eventos de búsqueda en los que el usuario ingresó una consulta de texto.

El attributionToken se muestra con los resultados de la consulta de búsqueda.

El documents objeto contiene el ID del documento (id) y su nombre de recurso (name).

  • Cuando incorporas o registras eventos de usuario a nivel del almacén de datos, puedes proporcionar el ID del documento (id) o el nombre de recurso (name).
  • Cuando incorporas o registras eventos a nivel de la ubicación, debes proporcionar el nombre de recurso del documento (name), ya que indica la ruta completa de un documento y hace referencia al almacén de datos en el que reside el documento. Puedes proporcionar el ID del documento como información adicional opcional.

JavaScript Pixel

var user_event = {
  "eventType": "search",
  "userPseudoId": "USER_PSEUDO_ID",
  "engine": "APP_ID",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "searchInfo": {
    "searchQuery": "SEARCH_QUERY",
  }, 
  "attributionToken": "ATTRIBUTION_TOKEN",
  "documents": [
    {
      "name": "DOCUMENT_NAME_1",
    },
    {
      "name": "DOCUMENT_NAME_2",
    },
  ]
};

BigQuery

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

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

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

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "engine",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "eventTime",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "searchInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "searchQuery",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "pageInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "pageCategory",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "attributionToken",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "documents",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

Acerca de la información del usuario

userPseudoId representa el identificador de usuario único y es obligatorio cuando registras un evento del usuario.

La información del usuario (UserInfo) incluida cuando registras un evento del usuario contiene el valor userPseudoId y, si está disponible, el valor userId. userId es opcional y se puede usar como un identificador único y persistente para un usuario en todos los dispositivos cada vez que este acceda a tu sitio. Cuando registras el userId para un usuario, las apps de Gemini Enterprise pueden generar resultados más personalizados para un usuario en varios dispositivos, como un dispositivo móvil y un navegador web.

Acerca de la marca de tiempo

Cuando registres un evento del usuario, asegúrate de incluir una marca de tiempo precisa de cuándo ocurrió el evento. Las marcas de tiempo precisas garantizan que tus eventos se almacenen en el orden correcto. Las marcas de tiempo se registran de forma automática para los eventos recopilados mediante JavaScript Pixel. Cuando importes eventos, debes proporcionar la marca de tiempo en el eventTime campo con el formato especificado por RFC 3339.