REST Resource: projects.locations.dataStores.userEvents

Recurso: UserEvent

UserEvent captura toda la información de metadatos que la API de Discovery Engine necesita saber sobre cómo interactúan los usuarios finales con tu sitio web.

Representación JSON 
{
  "eventType": string,
  "conversionType": string,
  "userPseudoId": string,
  "engine": string,
  "dataStore": string,
  "eventTime": string,
  "userInfo": {
    object (UserInfo)
  },
  "directUserRequest": boolean,
  "sessionId": string,
  "pageInfo": {
    object (PageInfo)
  },
  "attributionToken": string,
  "filter": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panel": {
    object (PanelInfo)
  },
  "searchInfo": {
    object (SearchInfo)
  },
  "completionInfo": {
    object (CompletionInfo)
  },
  "transactionInfo": {
    object (TransactionInfo)
  },
  "tagIds": [
    string
  ],
  "promotionIds": [
    string
  ],
  "attributes": {
    string: {
      "text": [
        string
      ],
      "numbers": [
        number
      ]
    },
    ...
  },
  "mediaInfo": {
    object (MediaInfo)
  },
  "panels": [
    {
      object (PanelInfo)
    }
  ],
  "feedback": {
    object (Feedback)
  },
  "entity": string
}
Campos
eventType

string

Obligatorio. Es el tipo de evento del usuario. Los valores permitidos son los siguientes:

Valores genéricos:

  • search: Busca documentos.
  • view-item: Es la vista detallada de la página de un documento.
  • view-item-list: Vista de un panel o lista ordenada de documentos.
  • view-home-page: Vista de la página principal.
  • view-category-page: Vista de una página de categoría, p.ej., Página principal > Hombres > Jeans

Valores relacionados con el comercio minorista:

  • add-to-cart: Agrega artículos al carrito, p. ej., en compras en línea de venta minorista.
  • purchase: Compra artículos

Valores relacionados con los medios:

  • media-play: Comenzar o reanudar la reproducción de un video, una canción, etcétera
  • media-complete: Terminó o se detuvo a mitad de un video, una canción, etcétera.

Valor de conversión personalizado:

  • conversion: Es el evento de conversión definido por el cliente.
conversionType

string

Es opcional. Es el tipo de conversión.

Se requiere si UserEvent.event_type es conversion. Es un nombre de conversión definido por el cliente en letras minúsculas o números separados por "-", como "mirar", "buena-visita", etcétera.

No configures el campo si UserEvent.event_type no es conversion. Esto combina el evento de conversión personalizado con eventos predefinidos, como search, view-item, etcétera.
userPseudoId

string

Obligatorio. Es un identificador único para hacer un seguimiento de los visitantes.

Por ejemplo, esto se podría implementar con una cookie HTTP, que debería poder identificar de forma única a un visitante en un solo dispositivo. Este identificador único no debe cambiar si el visitante accede al sitio web o sale de él.

No establezcas el campo en el mismo ID fijo para diferentes usuarios. Esto combina el historial de eventos de esos usuarios, lo que genera una calidad degradada del modelo.

El campo debe ser una cadena codificada en UTF-8 con un límite de 128 caracteres. De lo contrario, se muestra un error INVALID_ARGUMENT.

El campo no debe contener PII ni datos del usuario. Te recomendamos que utilices el ID de cliente de Google Analytics para este campo.
engine

string

El nombre del recurso Engine, con el formato projects/{project}/locations/{location}/collections/{collectionId}/engines/{engineId}.

Es opcional. Solo se requiere para los eventos de usuario producidos por Engine. Por ejemplo, eventos de usuario de la búsqueda combinada.
dataStore

string

Es el nombre completo del recurso DataStore, con el formato projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}.

Es opcional. Solo se requiere para los eventos del usuario cuyo almacén de datos no se puede determinar con UserEvent.engine o UserEvent.documents. Si el almacén de datos está configurado en el elemento superior de las solicitudes de escritura, importación o recopilación de eventos del usuario, se puede omitir este campo.
eventTime

string (Timestamp format)

Solo se requiere para el método UserEventService.ImportUserEvents. Es la marca de tiempo del momento en que ocurrió el evento del usuario.

Usa el formato RFC 3339, en el que el resultado generado siempre usará la normalización Z y los dígitos fraccionarios 0, 3, 6 o 9. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
userInfo

object (UserInfo)

Es la información sobre el usuario final.
directUserRequest

boolean

Se debe establecer en verdadero si la solicitud se realiza directamente desde el usuario final, en cuyo caso el UserEvent.user_info.user_agent se puede completar desde la solicitud HTTP.

Esta marca solo debe establecerse si la solicitud a la API se realiza directamente desde el usuario final, como una app para dispositivos móviles (y no si una puerta de enlace o un servidor procesan y envían los eventos del usuario).

No se debe configurar cuando se usa la etiqueta de JavaScript en UserEventService.CollectUserEvent.
sessionId

string

Es un identificador único para hacer un seguimiento de una sesión de visitante con un límite de 128 bytes. Una sesión es una agregación del comportamiento del usuario final en un período.

Un lineamiento general para propagar el sessionId:

  1. Si el usuario no tiene actividad durante 30 minutos, se debe asignar un nuevo sessionId.
  2. El sessionId debe ser único para todos los usuarios. Se sugiere usar uuid o agregar UserEvent.user_pseudo_id como prefijo.
pageInfo

object (PageInfo)

Metadatos de la página, como categorías y otra información importante para ciertos tipos de eventos, como view-category-page.
attributionToken

string

Es el token para atribuir una respuesta de la API a las acciones del usuario que activan el evento.

Se recomienda para los eventos de usuario que son el resultado de RecommendationService.Recommend. Este campo permite una atribución precisa del rendimiento del modelo de recomendación.

El valor debe ser uno de los siguientes:

Este token nos permite atribuir con precisión la vista de página o la finalización de la conversión al evento y a la respuesta de predicción específica que contiene este producto en el que se hizo clic o que se compró. Si el usuario hace clic en el producto K en los resultados de la recomendación, pasa RecommendResponse.attribution_token como un parámetro de URL a la página del producto K. Cuando se registren eventos en la página del producto K, registra el RecommendResponse.attribution_token en este campo.
filter

string

Es opcional. La sintaxis del filtro consta de un lenguaje de expresión para construir un predicado a partir de uno o más campos de los documentos que se filtran.

Un ejemplo es para los eventos de search, el SearchRequest asociado puede contener una expresión de filtro en SearchRequest.filter que cumpla con https://google.aip.dev/160#filtering.

Del mismo modo, para los eventos view-item-list que se generan a partir de un RecommendRequest, este campo se puede completar directamente desde RecommendRequest.filter de conformidad con https://google.aip.dev/160#filtering.

El valor debe ser una cadena codificada en UTF-8 con un límite de 1,000 caracteres. De lo contrario, se muestra un error INVALID_ARGUMENT.
documents[]

object (DocumentInfo)

Es la lista de objetos Document asociados con este evento del usuario.

Este campo es opcional, excepto para los siguientes tipos de eventos:

  • view-item
  • add-to-cart
  • purchase
  • media-play
  • media-complete

En un evento search, este campo representa los documentos que se devolvieron al usuario final en la página actual (es posible que el usuario final aún no haya terminado de navegar por toda la página). Cuando se devuelve una página nueva al usuario final, después de la paginación, el filtrado o la ordenación, incluso para la misma búsqueda, se desea un nuevo evento search con un UserEvent.documents diferente.
panel

object (PanelInfo)

Son los metadatos del panel asociados con este evento del usuario.
searchInfo

object (SearchInfo)

Detalles de SearchService.Search relacionados con el evento.

Este campo se debe establecer para el evento search.
completionInfo

object (CompletionInfo)

Detalles de CompletionService.CompleteQuery relacionados con el evento.

Este campo se debe establecer para el evento search cuando la función de autocompletar está habilitada y el usuario hace clic en una sugerencia de búsqueda.
transactionInfo

object (TransactionInfo)

Son los metadatos de la transacción (si los hay) asociados a este evento del usuario.
tagIds[]

string

Es una lista de identificadores de los grupos experimentales independientes a los que pertenece este evento del usuario. Se usa para distinguir entre los eventos de usuario asociados con diferentes configuraciones de experimentos.
promotionIds[]

string

Son los IDs de promoción si se trata de un evento asociado con promociones. Actualmente, este campo está restringido a un ID como máximo.
attributes

map (key: string, value: object)

Son funciones adicionales de eventos de usuario que se incluirán en el modelo de recomendación. Estos atributos NO deben contener datos que deban analizarse o procesarse más, p.ej., JSON o cualquier otra codificación.

Si proporcionas atributos personalizados para los eventos de usuario transferidos, también inclúyelos en los eventos de usuario que asocies con las solicitudes de predicción. El formato de los atributos personalizados debe ser coherente entre los eventos importados y los eventos proporcionados con las solicitudes de predicción. Esto permite que la API de Discovery Engine use esos atributos personalizados cuando entrena modelos y publica predicciones, lo que ayuda a mejorar la calidad de las recomendaciones.

Este campo debe cumplir con todos los criterios que se indican a continuación; de lo contrario, se devolverá un error INVALID_ARGUMENT:

  • La clave debe ser una cadena codificada en UTF-8 con un límite de 5,000 caracteres.
  • En el caso de los atributos de texto, se permiten hasta 400 valores. No se permiten valores vacíos. Cada valor debe ser una cadena codificada en UTF-8 con un límite de 256 caracteres.
  • En el caso de los atributos numéricos, se permiten hasta 400 valores.

En el caso de las recomendaciones de productos, un ejemplo de información adicional del usuario es traffic_channel, que indica cómo llega un usuario al sitio. Los usuarios pueden llegar al sitio directamente, a través de la Búsqueda de Google o de otras formas.
attributes.text[]

string

Son los valores de texto de este atributo personalizado. Por ejemplo, ["yellow", "green"] cuando la clave es "color".

No se permite una cadena vacía. De lo contrario, se muestra un error INVALID_ARGUMENT.

Se debe establecer exactamente uno de los campos CustomAttribute.text o CustomAttribute.numbers. De lo contrario, se muestra un error INVALID_ARGUMENT.
attributes.numbers[]

number

Son los valores numéricos de este atributo personalizado. Por ejemplo, [2.3, 15.4] cuando la clave es "lengths_cm".

Se debe establecer exactamente uno de los campos CustomAttribute.text o CustomAttribute.numbers. De lo contrario, se muestra un error INVALID_ARGUMENT.
mediaInfo

object (MediaInfo)

Es información específica de los medios.
panels[]

object (PanelInfo)

Es opcional. Es la lista de paneles asociados con este evento. Se usa para los datos de impresiones a nivel de la página.
feedback

object (Feedback)

Es opcional. Este campo es opcional, excepto para los tipos de eventos add-feedback.
entity

string

Es opcional. Representa la entidad para los clientes que pueden ejecutar varias entidades, dominios, sitios o regiones diferentes, por ejemplo, Google US, Google Ads, Waymo, google.com, youtube.com, etcétera. Te recomendamos que configures entity para obtener mejores resultados de búsqueda, finalización y predicción por entidad.

PageInfo

Información detallada de la página

Representación JSON 
{
  "pageviewId": string,
  "pageCategory": string,
  "uri": string,
  "referrerUri": string
}
Campos
pageviewId

string

Es un ID único de una vista de página web.

Este valor debe ser el mismo para todos los eventos del usuario activados desde la misma vista de página. Por ejemplo, la vista de una página de detalles del artículo podría activar varios eventos a medida que el usuario navega por la página. La propiedad pageviewId debe ser la misma para todos estos eventos, de modo que se puedan agrupar correctamente.

Cuando se usan los informes de eventos del cliente con el píxel de JavaScript y Google Tag Manager, este valor se completa automáticamente.
pageCategory

string

Es la categoría más específica asociada a una página de categoría.

Para representar la ruta de acceso completa de la categoría, usa el signo ">" para separar las diferentes jerarquías. Si ">" forma parte del nombre de la categoría, reemplázalo por otros caracteres.

Las páginas de categorías incluyen páginas especiales, como las de ofertas o promociones. Por ejemplo, una página de ofertas especiales puede tener la siguiente jerarquía de categorías: "pageCategory" : "Sales > 2017 Black Friday Deals".

Obligatorio para los eventos de view-category-page. Otros tipos de eventos no deben establecer este campo. De lo contrario, se muestra un error INVALID_ARGUMENT.
uri

string

Es la URL completa (window.location.href) de la página actual del usuario.

Cuando se usan los informes de eventos del cliente con el píxel de JavaScript y Google Tag Manager, este valor se completa automáticamente. La longitud máxima es de 5,000 caracteres.
referrerUri

string

Es la URL de referencia de la página actual.

Cuando se usan los informes de eventos del cliente con el píxel de JavaScript y Google Tag Manager, este valor se completa automáticamente. Sin embargo, algunas restricciones de privacidad del navegador pueden hacer que este campo esté vacío.

DocumentInfo

Es la información detallada del documento asociada a un evento del usuario.

Representación JSON 
{
  "promotionIds": [
    string
  ],
  "joined": boolean,

  // Union field document_descriptor can be only one of the following:
  "id": string,
  "name": string,
  "uri": string
  // End of list of possible types for union field document_descriptor.
  "quantity": integer,
  "conversionValue": number
}
Campos
promotionIds[]

string

Son los IDs de las promociones asociadas con este documento. Actualmente, este campo está restringido a un ID como máximo.
joined

boolean

Solo salida. Indica si se puede encontrar el documento al que se hace referencia en el almacén de datos.

Campo de unión document_descriptor. Es un descriptor obligatorio del Document asociado.

  • Si se especifica id, se usan los valores predeterminados para {location}, {collection_id}, {data_store_id} y {branch_id} cuando se realiza la anotación con el documento almacenado.

  • Si se especifica name, se usarán los valores proporcionados (se permiten valores predeterminados) para {location}, {collection_id}, {data_store_id} y {branch_id} cuando se anote con el documento almacenado. document_descriptor puede ser solo uno de los siguientes:
id

string

ID del recurso Document.
name

string

Es el nombre completo del recurso Document, con el siguiente formato: projects/{project}/locations/{location}/collections/{collectionId}/dataStores/{dataStoreId}/branches/{branchId}/documents/{documentId}
uri

string

El URI de Document, que solo se permite para los almacenes de datos de sitios web.
quantity

integer

Cantidad del documento asociado con el evento del usuario. El valor predeterminado es 1.

Por ejemplo, este campo es 2 si dos cantidades del mismo documento están involucradas en un evento add-to-cart.

Se requiere para los eventos de los siguientes tipos:

  • add-to-cart
  • purchase
conversionValue

number

Es opcional. Es el valor de conversión asociado a este documento. Se debe establecer si UserEvent.event_type es "conversion".

Por ejemplo, un valor de 1,000 significa que se dedicaron 1,000 segundos a ver un documento para el tipo de conversión watch.

PanelInfo

Es la información detallada del panel asociada a un evento del usuario.

Representación JSON 
{
  "panelId": string,
  "displayName": string,
  "documents": [
    {
      object (DocumentInfo)
    }
  ],
  "panelPosition": integer,
  "totalPanels": integer
}
Campos
panelId

string

Obligatorio. Es el ID del panel.
displayName

string

Es el nombre visible del panel.
documents[]

object (DocumentInfo)

Es opcional. Son los IDs de los documentos asociados con este panel.
panelPosition

integer

Posición ordenada del panel, si se muestra al usuario con otros paneles. Si se establece, también se debe establecer totalPanels.
totalPanels

integer

Es la cantidad total de paneles, incluido este, que se muestran al usuario. Se debe establecer si se configura panelPosition.

SearchInfo

Es información detallada sobre la búsqueda.

Representación JSON 
{
  "searchQuery": string,
  "orderBy": string,
  "offset": integer
}
Campos
searchQuery

string

Es la búsqueda del usuario.

Consulta SearchRequest.query para obtener la definición.

El valor debe ser una cadena codificada en UTF-8 con un límite de 5,000 caracteres. De lo contrario, se muestra un error INVALID_ARGUMENT.

Se requiere al menos uno de los parámetros searchQuery o PageInfo.page_category para los eventos search. Otros tipos de eventos no deben establecer este campo. De lo contrario, se muestra un error INVALID_ARGUMENT.
orderBy

string

Es el orden en el que se muestran los productos, si corresponde.

Consulta SearchRequest.order_by para ver la definición y la sintaxis.

El valor debe ser una cadena codificada en UTF-8 con un límite de 1,000 caracteres. De lo contrario, se muestra un error INVALID_ARGUMENT.

Solo se puede configurar para eventos search. Otros tipos de eventos no deben establecer este campo. De lo contrario, se muestra un error INVALID_ARGUMENT.
offset

integer

Es un número entero que especifica el desplazamiento actual para la paginación (la ubicación inicial indexada en 0, entre los productos que la API considera relevantes).

Consulta SearchRequest.offset para obtener la definición.

Si este campo es negativo, se devuelve un INVALID_ARGUMENT.

Solo se puede configurar para eventos search. Otros tipos de eventos no deben establecer este campo. De lo contrario, se muestra un error INVALID_ARGUMENT.

CompletionInfo

Es información detallada sobre la finalización, incluido el token de atribución de finalización y la información de finalización en la que se hizo clic.

Representación JSON 
{
  "selectedSuggestion": string,
  "selectedPosition": integer
}
Campos
selectedSuggestion

string

El usuario final seleccionó CompleteQueryResponse.QuerySuggestion.suggestion.
selectedPosition

integer

Posición CompleteQueryResponse.QuerySuggestion.suggestion seleccionada por el usuario final, a partir de 0.

TransactionInfo

Una transacción representa toda la transacción de compra.

Representación JSON 
{
  "currency": string,
  "transactionId": string,
  "value": number,
  "tax": number,
  "cost": number,
  "discountValue": number
}
Campos
currency

string

Obligatorio. Código de moneda. Utiliza el código ISO-4217 de tres caracteres.
transactionId

string

Es el ID de transacción con un límite de 128 caracteres.
value

number

Obligatorio. Es el valor total distinto de cero asociado a la transacción. Este valor puede incluir el envío, los impuestos o cualquier otro ajuste al valor total que desees incluir.
tax

number

Son todos los impuestos asociados a la transacción.
cost

number

Son todos los costos asociados a los productos. Estos pueden ser costos de fabricación, gastos de envío que no paga el usuario final o cualquier otro costo, de modo que se cumpla la siguiente ecuación:
discountValue

number

Es el valor total de los descuentos aplicados a esta transacción. Esta cifra se debe excluir de TransactionInfo.value.

Por ejemplo, si un usuario pagó un importe de TransactionInfo.value, el valor nominal (antes del descuento) de la transacción es la suma de TransactionInfo.value y TransactionInfo.discount_value.

Esto significa que la ganancia se calcula de la misma manera, independientemente del valor del descuento, y que TransactionInfo.discount_value puede ser mayor que TransactionInfo.value:

MediaInfo

Es información de eventos de usuarios específica de los medios.

Representación JSON 
{
  "mediaProgressDuration": string,
  "mediaProgressPercentage": number
}
Campos
mediaProgressDuration

string (Duration format)

Es el tiempo de progreso de los medios en segundos, si corresponde. Por ejemplo, si el usuario final terminó de mirar 90 segundos de un video de reproducción, MediaInfo.media_progress_duration.seconds debe establecerse en 90.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".
mediaProgressPercentage

number

El progreso del contenido multimedia se debe calcular solo con el valor de mediaProgressDuration en relación con la duración total del contenido multimedia.

Este valor debe ser mayor o igual que [0, 1.0].

Si no se trata de una reproducción o no se puede calcular el progreso (p.ej., una transmisión en vivo en curso), este campo debe quedar sin configurar.

Comentarios

Es la información sobre los comentarios de los usuarios. Esta información se usará para fines de registro y métricas.

Representación JSON 
{
  "feedbackType": enum (FeedbackType),
  "reasons": [
    enum (Reason)
  ],
  "comment": string,
  "conversationInfo": {
    object (ConversationInfo)
  },
  "llmModelVersion": string,
  "feedbackSource": enum (FeedbackSource),
  "componentVersion": string,
  "dataTermsAccepted": boolean
}
Campos
feedbackType

enum (FeedbackType)

Obligatorio. Indica si el usuario proporciona comentarios positivos o negativos. Si el usuario brinda comentarios negativos, es posible que haya más detalles.
reasons[]

enum (Reason)

Es opcional. Es el motivo por el que el usuario indica que no le gusta el contenido.
comment

string

Es opcional. Es el comentario adicional del usuario sobre la opinión si este indica que no le gusta.
conversationInfo

object (ConversationInfo)

Es la información de la conversación relacionada cuando el usuario proporciona comentarios.
llmModelVersion

string

Es la versión del modelo de LLM que se usó para generar la respuesta.
feedbackSource

enum (FeedbackSource)

Es opcional. Componente de la IU del que proviene el comentario del usuario, que podría ser GOOGLE_CONSOLE, GOOGLE_WIDGET o GOOGLE_WEBAPP.
componentVersion

string

Es opcional. Es la versión del componente desde el que se envía este informe.
dataTermsAccepted

boolean

Es opcional. Indica si el cliente aceptó las condiciones de uso de datos.

FeedbackType

Es el tipo de comentarios que brinda el usuario.

Enums
FEEDBACK_TYPE_UNSPECIFIED Tipo de comentarios sin especificar.
LIKE El usuario envía comentarios positivos.
DISLIKE El usuario envía comentarios negativos.

Motivo

Es el motivo por el que el usuario envía comentarios negativos.

Enums
REASON_UNSPECIFIED Motivo sin especificar.
INACCURATE_RESPONSE La respuesta es imprecisa.
NOT_RELEVANT La respuesta no es pertinente.
INCOMPREHENSIVE La respuesta es incomprensible.
OFFENSIVE_OR_UNSAFE La respuesta es ofensiva o no es segura.
FORMAT_AND_STYLES La respuesta no tiene un formato adecuado.
BAD_CITATION La respuesta no está bien asociada con la búsqueda.
CANVAS_NOT_GENERATED No se generó el lienzo esperado para la respuesta.
CANVAS_QUALITY_BAD El lienzo generado es de mala calidad (p.ej., es impreciso, está incompleto o tiene un formato deficiente).
CANVAS_EXPORT_FAILED No se pudo exportar el lienzo generado (p.ej., no se completó correctamente la descarga o la acción de exportación externa).

ConversationInfo

Es la información de la conversación, como el índice de la pregunta y el nombre de la sesión.

Representación JSON 
{
  "questionIndex": integer,
  "session": string,
  "query": {
    object (Query)
  },
  "assistToken": string,
  "answerQueryToken": string
}
Campos
questionIndex

integer

Índice de la entrada del usuario en los mensajes de la conversación.
session

string

Nombre de la sesión recién generada o continuada.
query

object (Query)

Obligatorio. Es la búsqueda del usuario.
assistToken

string

Es opcional. Es el token que se puede usar para recuperar el registro del asistente.
answerQueryToken

string

Es opcional. Es el token que se podría usar para recuperar el registro de respuestas.

FeedbackSource

Fuente de los comentarios según la integración.

Enums
FEEDBACK_SOURCE_UNSPECIFIED Es la fuente de comentarios no especificada.
GOOGLE_CONSOLE La fuente de comentarios es la consola de Google.
GOOGLE_WIDGET La fuente de comentarios es el widget de Google.
GOOGLE_WEBAPP La fuente de comentarios es la app web de Google.
GOOGLE_AGENTSPACE_MOBILE La fuente de comentarios es la app de Google Agentspace para dispositivos móviles.

Métodos

collect

 Escribe un solo evento del usuario desde el navegador.

import

 Importación masiva de eventos de usuario.

purge

 Borra de forma permanente todos los eventos del usuario especificados por el filtro proporcionado.

write

 Escribe un solo evento del usuario.