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)
    }
  ]
}
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: Es la 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: 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

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 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 o sale del sitio web.

No establezcas el campo en el mismo ID fijo para diferentes usuarios. Esto combina el historial de eventos de esos usuarios, lo que degrada la calidad 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 uses 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}.

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 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 estará normalizado a Z y usará 0, 3, 6 o 9 dígitos fraccionarios. 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 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 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 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

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 se ajuste a 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 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 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 longitud 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)

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

UserInfo

Es la información de un usuario final.

Representación JSON 
{
  "userId": string,
  "userAgent": string,
  "timeZone": string
}
Campos
userId

string

Se recomienda para los usuarios que accedieron a sus cuentas. Es el identificador único del usuario que accedió, como un nombre de usuario. No se establece para usuarios anónimos.

Siempre usa un valor hash para este ID.

No establezcas el campo en el mismo ID fijo para diferentes usuarios. Esto combina el historial de eventos de esos usuarios, lo que degrada la calidad 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.
userAgent

string

Es el usuario-agente incluido en el encabezado HTTP.

El campo 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.

No se debe configurar cuando se utiliza el informe de eventos del cliente con GTM o la etiqueta de JavaScript en UserEventService.CollectUserEvent, o si se configura UserEvent.direct_user_request.
timeZone

string

Opcional. Zona horaria de IANA, p.ej., Europe/Budapest.

PageInfo

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 que se activen 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 utiliza el registro de eventos del cliente con JavaScript Pixel 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 utiliza el registro de eventos del cliente con JavaScript Pixel 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 utiliza el registro de eventos del cliente con JavaScript Pixel 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 usarán los valores predeterminados de {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. document_descriptor puede ser solo uno de los siguientes:
id

string

ID del recurso Document.
name

string

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, solo se permite para los almacenes de datos de sitios web.
quantity

integer

Cantidad del documento asociado al 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.

Obligatorio para los eventos de los siguientes tipos:

  • add-to-cart
  • purchase
conversionValue

number

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)

Opcional. Son los IDs de los documentos asociados con este panel.
panelPosition

integer

Es la 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 no nulo 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ó 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 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 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 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.

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.