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 los usuarios finales interactúan 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: Vista detallada de la página de un documento.
  • view-item-list: Vista de un panel o una 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: Se terminó o se detuvo a mitad de un video, una canción, etcétera.

Valor de conversión personalizado:

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

string

Es opcional. Es el tipo de conversión.

Obligatorio 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 establezcas 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 mezcla el historial de eventos de esos usuarios, lo que genera una calidad del modelo degradada.

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

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

string

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

Es opcional. Solo se requiere para los eventos del 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.

Este parámetro de marcas solo se debe establecer 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 longitud de 128 bytes. Una sesión es una agregación del comportamiento de un 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 fundamental 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 finalización de una conversión o una vista de página 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 RecommendResponse.attribution_token en este campo.
filter

string

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

Un ejemplo es para los eventos 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 devuelve un error INVALID_ARGUMENT.
documents[]

object (DocumentInfo)

Es la lista de Documents 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 el ordenamiento, incluso para la misma búsqueda, se desea un evento search nuevo 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 máximo de un ID.
attributes

map (key: string, value: object)

Es opcional. Son funciones adicionales del evento 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 debes incluirlos 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 permiten cadenas vacías. De lo contrario, se devuelve un error INVALID_ARGUMENT.

Se debe establecer exactamente uno de los valores 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 valores 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, autocompletado y predicción por entidad.

PageInfo

Es información detallada de la página.

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

string

Es el 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 mientras 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 usa el informe 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 devuelve un error INVALID_ARGUMENT.
uri

string

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

Cuando se usa el informe 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 usa el informe 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,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "id": string,
  "name": string,
  "uri": string
  // End of mutually exclusive fields.
  "quantity": integer,
  "conversionValue": number
}
Campos
promotionIds[]

string

Son los IDs de promoción asociados a este documento. Actualmente, este campo está restringido a un máximo de un ID.
joined

boolean

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

Es un descriptor obligatorio del Document asociado.

  • Si se especifica id, se usarán los valores predeterminados para {location}, {collection_id}, {data_store_id} y {branch_id} cuando se anote 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. La siguiente es una lista de campos mutuamente excluyentes. Como máximo, se establecerá uno de los campos en una respuesta:
id

string

Es el ID del recurso Document.
name

string

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

string

El URI de Document, solo se permite para los almacenes de datos de sitios web.
Fin de los campos mutuamente excluyentes.
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 de 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 configurar si UserEvent.event_type es "conversión".

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 documento 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 configurar si se establece panelPosition.

SearchInfo

Es información detallada de la búsqueda.

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

string

Es opcional. 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 devuelve 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 devuelve 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 devuelve un error INVALID_ARGUMENT.

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

integer

Es un número entero que especifica el desplazamiento actual para la paginación (la ubicación de inicio 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 devuelve 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 la finalización en la que se hizo clic.

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

string

Es opcional. 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. Es el código de moneda. Usa 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 no nulo asociado a la transacción. Este valor puede incluir los costos de envío, los impuestos y otros ajustes 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 corren por cuenta del usuario final o cualquier otro costo, de modo que:
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ó el importe 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 específica del evento del usuario para los medios.

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

string (Duration format)

Es el tiempo de progreso del contenido multimedia 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 de los medios solo se debe calcular con mediaProgressDuration en relación con la duración total del contenido multimedia.

Este valor debe estar entre [0, 1.0], inclusive.

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 del usuario. 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 da 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 si el usuario indica que no le gusta.
comment

string

Es opcional. Es el comentario adicional del usuario sobre los comentarios si el usuario indica que no le gusta.
conversationInfo

object (ConversationInfo)

Es la información de la conversación relacionada cuando el usuario envía 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 provienen los comentarios 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 No se especificó el tipo de comentarios.
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 no especificado.
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., impreciso, incompleto o con 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 preguntas y el nombre de la sesión.

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

integer

Índice de la entrada del usuario dentro de 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 puede usar para recuperar el registro de respuestas.
taskName

string

Es opcional. Es el nombre completo del recurso de la tarea de Sobi si la conversación se controló con una tarea de agente de larga duración. Formato: projects/{project}/locations/{location}/tasks/{taskId}

FeedbackSource

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

Enums
FEEDBACK_SOURCE_UNSPECIFIED Fuente de comentarios no especificada.
GOOGLE_CONSOLE La fuente de comentarios es Google Console.
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 para dispositivos móviles de Google Agentspace.

Métodos

collect

 Escribe un solo evento de 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 de usuario.