REST Resource: projects.locations.dataStores.userEvents

Recurso: UserEvent

UserEvent recoge toda la información de metadatos que necesita la API Discovery Engine para saber cómo interactúan los usuarios finales con su 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)
    }
  ]
}
Campos
eventType

string

Obligatorio. Tipo de evento de usuario. Los valores permitidos son:

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, por ejemplo, Inicio > Hombre > Vaqueros

Valores relacionados con el comercio:

  • add-to-cart: añadir uno o varios artículos al carrito(por ejemplo, en una tienda online)
  • purchase: comprar uno o varios artículos

Valores relacionados con los medios:

  • media-play: empezar o reanudar la reproducción de un vídeo, una canción, etc.
  • media-complete: se ha terminado o se ha detenido a mitad de un vídeo, una canción, etc.

Valor de conversión personalizado:

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

string

Opcional. 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 "watch" o "good-visit".

No definas el campo si UserEvent.event_type no es conversion. De esta forma, el evento de conversión personalizado se combina con eventos predefinidos, como search, view-item, etc.
userPseudoId

string

Obligatorio. Identificador único para hacer un seguimiento de los visitantes.

Por ejemplo, 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 debería cambiar si el visitante inicia o cierra sesión en el sitio web.

No asigne el mismo ID fijo al campo para diferentes usuarios. De esta forma, se mezclan los historiales de eventos de esos usuarios, lo que provoca que la calidad del modelo se vea afectada.

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 información personal identificable ni datos de usuario. Le recomendamos que utilice el ID de cliente de Google Analytics en este campo.
engine

string

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

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

string

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

Opcional. Solo es obligatorio para los eventos de usuario cuyo almacén de datos no se pueda determinar mediante UserEvent.engine o UserEvent.documents. Si el almacén de datos se define en el elemento superior de las solicitudes de escritura, importación o recogida de eventos de usuario, este campo se puede omitir.
eventTime

string (Timestamp format)

Solo se requiere para el método UserEventService.ImportUserEvents. Marca de tiempo de cuándo se produjo el evento del usuario.

Usa RFC 3339, donde la salida generada siempre se normaliza con Z y usa 0, 3, 6 o 9 dígitos fraccionarios. También se aceptan otros desplazamientos distintos de "Z". Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".
userInfo

object (UserInfo)

Información sobre el usuario final.
directUserRequest

boolean

Debe asignarse el valor true si la solicitud se envía directamente desde el usuario final. En ese caso, el UserEvent.user_info.user_agent se puede rellenar a partir de la solicitud HTTP.

Esta marca solo debe definirse si la solicitud de la API se realiza directamente desde el usuario final, como una aplicación móvil (y no si una pasarela o un servidor procesan y envían los eventos del usuario).

No se debe definir cuando se utilice la etiqueta JavaScript en UserEventService.CollectUserEvent.
sessionId

string

Identificador único para hacer un seguimiento de la sesión de un visitante. Tiene un límite de 128 bytes. Una sesión es una agregación del comportamiento de un usuario final en un periodo determinado.

Directriz general para rellenar el ID de sesión:

  1. Si el usuario no tiene actividad durante 30 minutos, se debe asignar un nuevo ID de sesión.
  2. El ID de sesión debe ser único para cada usuario. Te recomendamos que uses UUID o que añadas UserEvent.user_pseudo_id como prefijo.
pageInfo

object (PageInfo)

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

string

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

Muy recomendable para eventos de usuario que sean el resultado de RecommendationService.Recommend. Este campo permite atribuir con precisión el rendimiento del modelo de recomendación.

El valor debe ser uno de los siguientes:

Este token nos permite atribuir con precisión la visualización de la página o la finalización de la conversión al evento y a la respuesta de predicción concreta que contiene este producto en el que se ha hecho clic o que se ha comprado. Si el usuario hace clic en el producto K en los resultados de recomendación, pasa RecommendResponse.attribution_token como parámetro de URL a la página del producto K. Cuando registre eventos en la página del producto K, registre el RecommendResponse.attribution_token en este campo.
filter

string

La sintaxis del filtro consta de un lenguaje de expresiones para crear un predicado a partir de uno o varios campos de los documentos que se van a filtrar.

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

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

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

object (DocumentInfo)

Lista de Documents asociados a este evento de usuario.

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

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

En un evento search, este campo representa los documentos devueltos 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 consulta, se recomienda usar un evento search con un UserEvent.documents diferente.
panel

object (PanelInfo)

Metadatos del panel asociados a este evento de usuario.
searchInfo

object (SearchInfo)

SearchService.Search detalles relacionados con el evento.

Este campo debe definirse para el evento search.
completionInfo

object (CompletionInfo)

CompletionService.CompleteQuery detalles relacionados con el evento.

Este campo debe definirse en el evento search cuando la función de autocompletado esté habilitada y el usuario haga clic en una sugerencia de búsqueda.
transactionInfo

object (TransactionInfo)

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

string

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

string

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

map (key: string, value: object)

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, como JSON u otras codificaciones.

Si proporciona atributos personalizados para los eventos de usuario insertados, inclúyalos también en los eventos de usuario que asocie a 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. De esta forma, la API Discovery Engine puede usar esos atributos personalizados al entrenar modelos y ofrecer predicciones, lo que ayuda a mejorar la calidad de las recomendaciones.

Este campo debe cumplir 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 una longitud máxima de 5000 caracteres.
  • En el caso de los atributos de texto, se permiten 400 valores como máximo. 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 de número, se permiten 400 valores como máximo.

En el caso de las recomendaciones de productos, un ejemplo de información adicional sobre el 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

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 definir exactamente una de las propiedades CustomAttribute.text o CustomAttribute.numbers. De lo contrario, se devuelve un error INVALID_ARGUMENT.
attributes.numbers[]

number

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

Se debe definir exactamente una de las propiedades CustomAttribute.text o CustomAttribute.numbers. De lo contrario, se devuelve un error INVALID_ARGUMENT.
mediaInfo

object (MediaInfo)

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

object (PanelInfo)

Opcional. Lista de paneles asociados a este evento. Se usa para los datos de impresiones a nivel de página.

PageInfo

Información detallada de la página.

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

string

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

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

Si usa el registro de eventos del lado del cliente con el píxel de JavaScript y Google Tag Manager, este valor se rellena automáticamente.
pageCategory

string

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

Para representar la ruta completa de la categoría, use el signo ">" para separar las distintas jerarquías. Si el carácter ">" forma parte del nombre de la categoría, sustitúyelo por otro u otros caracteres.

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

Es obligatorio en los eventos view-category-page. Otros tipos de eventos no deben definir este campo. De lo contrario, se devuelve un error INVALID_ARGUMENT.
uri

string

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

Si usa el registro de eventos del lado del cliente con el píxel de JavaScript y Google Tag Manager, este valor se rellena automáticamente. La longitud máxima es de 5000 caracteres.
referrerUri

string

La URL referente de la página actual.

Si usa el registro de eventos del lado del cliente con el píxel de JavaScript y Google Tag Manager, este valor se rellena automáticamente. Sin embargo, es posible que este campo esté vacío debido a algunas restricciones de privacidad del navegador.

DocumentInfo

Información detallada del documento asociado a un evento de 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

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

boolean

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

Campo de unión document_descriptor. Descriptor obligatorio del Document asociado.

  • Si se especifica id, se usarán los valores predeterminados de {location}, {collection_id}, {data_store_id} y {branch_id} al anotar con el documento almacenado.

  • Si se especifica name, se usarán los valores proporcionados (se permiten valores predeterminados) de {location}, {collection_id}, {data_store_id} y {branch_id} al anotar con el documento almacenado. document_descriptor solo puede ser una de estas dos opciones:
id

string

El ID de recurso Document.
name

string

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

string

El URI Document solo se permite en los almacenes de datos de sitios web.
quantity

integer

Cantidad del documento asociado al evento de usuario. El valor predeterminado es 1.

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

Obligatorio para los eventos de los siguientes tipos:

  • add-to-cart
  • purchase
conversionValue

number

Opcional. Valor de conversión asociado a este documento. Se debe definir si UserEvent.event_type es "conversion".

Por ejemplo, el valor 1000 significa que se han dedicado 1000 segundos a ver un documento del tipo de conversión watch.

PanelInfo

Información detallada del panel asociada a un evento de usuario.

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

string

Obligatorio. El ID del panel.
displayName

string

Nombre visible del panel.
documents[]

object (DocumentInfo)

Opcional. Los IDs de documento asociados a este panel.
panelPosition

integer

La posición ordenada del panel, si se muestra al usuario junto con otros paneles. Si se define, también se debe definir totalPanels.
totalPanels

integer

El número total de paneles, incluido este, que se muestran al usuario. Se debe definir si se define panelPosition.

SearchInfo

Información de búsqueda detallada.

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

string

La consulta de búsqueda del usuario.

Consulta la definición en SearchRequest.query.

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

Se requiere al menos uno de los dos para los eventos search.searchQueryPageInfo.page_category Otros tipos de eventos no deben definir este campo. De lo contrario, se devuelve un error INVALID_ARGUMENT.
orderBy

string

El orden en el que se devuelven los productos, si procede.

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 1000 caracteres. De lo contrario, se devuelve un error INVALID_ARGUMENT.

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

integer

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

Consulta la definición en SearchRequest.offset.

Si este campo es negativo, se devuelve un error INVALID_ARGUMENT.

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

CompletionInfo

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 ha hecho clic.

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

string

Usuario final seleccionado: CompleteQueryResponse.QuerySuggestion.suggestion.
selectedPosition

integer

Posición CompleteQueryResponse.QuerySuggestion.suggestion seleccionada por el usuario final, empezando por 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. Usa el código ISO 4217 de tres caracteres.
transactionId

string

El ID de transacción, que tiene un límite de 128 caracteres.
value

number

Obligatorio. Valor total distinto de cero asociado a la transacción. Este valor puede incluir los gastos de envío, los impuestos u otros ajustes del valor total que quiera incluir.
tax

number

Todos los impuestos asociados a la transacción.
cost

number

Todos los costes asociados a los productos. Pueden ser costes de fabricación, gastos de envío que no corran a cargo del usuario final o cualquier otro coste, de modo que:
discountValue

number

Valor total de los descuentos aplicados a esta transacción. Esta cifra debe excluirse de TransactionInfo.value

Por ejemplo, si un usuario ha pagado 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 los beneficios se calculan de la misma forma, independientemente del valor del descuento, y que TransactionInfo.discount_value puede ser mayor que TransactionInfo.value:

MediaInfo

Información de eventos de usuario específicos de medios.

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

string (Duration format)

El tiempo de progreso del contenido multimedia en segundos, si procede. Por ejemplo, si el usuario final ha visto 90 segundos de un vídeo de reproducción, MediaInfo.media_progress_duration.seconds debe ser 90.

Duración en segundos con hasta nueve decimales, que termina con "s". Por ejemplo: "3.5s".
mediaProgressPercentage

number

El progreso del contenido multimedia debe calcularse usando solo el 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 (por ejemplo, en una emisión en directo en curso), este campo no debe definirse.

Métodos

collect

 Escribe un solo evento de usuario desde el navegador.

import

 Importación masiva de eventos de usuario.

purge

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

write

 Escribe un solo evento de usuario.