En esta página, se describen los eventos de usuario para las apps de Gemini Enterprise, incluidos los tipos de eventos de usuario, los requisitos y los ejemplos de tipos de eventos de usuario.
Si usas las APIs de Gemini Enterprise en tus propias apps, debes configurar la búsqueda en tu app para obtener los eventos de usuario y, luego, agregar los datos de eventos de usuario a tu app de Gemini Enterprise.
Si creas tu app a través de la Google Cloud consola, no necesitas importar eventos de usuario de forma manual (y no necesitas leer esta página).
Para obtener ayuda con el registro de eventos de usuario, consulta Registra eventos de usuario en tiempo real. Para importar eventos de usuario anteriores de forma masiva, consulta Importa eventos de usuario históricos.
Tipos de eventos del usuario
Puedes registrar los siguientes tipos de eventos de usuario a medida que los usuarios finales exploran o buscan en tu sitio:
| Nombre del evento del usuario | Acción del usuario |
|---|---|
view-item |
Permite ver los detalles de un documento. |
search |
Busca datos en la app de Gemini Enterprise. |
Para obtener detalles sobre el objeto de evento de usuario, consulta la
[documentación de referencia de la API de UserEvent][user-event].
Ejemplos y esquemas de los tipos de eventos del usuario
En esta sección, se proporcionan los formatos de datos para cada tipo de evento que admiten las apps de Gemini Enterprise. Se proporcionan ejemplos para el píxel de JavaScript. En el caso de BigQuery, se proporciona el esquema de tabla completo para cada tipo.
Para todos los tipos de eventos de usuario, userId es opcional.
Para obtener más detalles sobre el objeto de evento de usuario, consulta la
[documentación de referencia de la API de UserEvent][user-event].
view-item
A continuación, se muestra el formato de datos del evento de usuario view-item.
Requisitos de optimización de la búsqueda para los eventos de vista de elemento
Para permitir que la automatización de anuncios de búsqueda optimice automáticamente la experiencia de búsqueda en función de las tendencias generales de los usuarios, sube los siguientes datos.
Los eventos se deben subir, al menos, diariamente con un retraso máximo de 24 horas.
| Métrica de eventos | Volumen y frecuencia de los eventos | Descripción |
|---|---|---|
Volumen de eventos de view-item |
250,000 elementos de vista |
Se requieren al menos 250,000 elementos de vista para optimizar la experiencia de búsqueda en función de los eventos transferidos. |
Objeto view-item mínimo obligatorio
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario view-item.
El objeto
documents
contiene el ID del documento
(id) y su nombre de
recurso (name).
- Cuando transfieres o registras eventos de usuario a nivel del almacén de datos, puedes proporcionar
el ID del documento (
id) o el nombre del recurso (name). - Cuando transfieres o registras eventos a nivel de ubicación, debes proporcionar el
nombre del recurso del documento (
name) porque indica la ruta de acceso completa de un documento y hace referencia al almacén de datos en el que reside el documento. Puedes proporcionar el ID del documento como información adicional opcional.
JavaScript Pixel
var user_event = {
"eventType": "view-item",
"userPseudoId": "USER_PSEUDO_ID",
"engine": "APP_ID",
"eventTime": "2020-01-01T03:33:33.000001Z",
"documents": [{
"name": "DOCUMENT_NAME"
}]
};
BigQuery
Este es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.
Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para
los campos opcionales se establecen en NULLABLE.
Ten en cuenta que se requiere eventTime para importar eventos con
BigQuery. eventTime es una cadena con un formato de marca de tiempo.
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "userPseudoId", "type": "STRING", "mode": "REQUIRED" }, { "name": "engine", "type": "STRING", "mode": "NULLABLE" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "userInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "userId", "type": "STRING", "mode": "NULLABLE" }, { "name": "userAgent", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "pageInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "pageviewId", "type": "STRING", "mode": "NULLABLE" }, { "name": "uri", "type": "STRING", "mode": "NULLABLE" }, { "name": "referrerUri", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "documents", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "tagIds", "type": "STRING", "mode": "REPEATED" }, { "name": "attributes", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "example_text_attribute", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "text", "type": "STRING", "mode": "REPEATED" } ] }, { "name": "example_number_attribute", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "numbers", "type": "NUMERIC", "mode": "REPEATED" } ] } ] } ]
search
A continuación, se muestra el formato del evento de usuario search.
Requisitos de optimización de la búsqueda para los eventos de búsqueda
Para permitir que la automatización de anuncios de búsqueda optimice automáticamente la experiencia de búsqueda en función de las tendencias generales de los usuarios, sube los siguientes datos.
Los eventos se deben subir, al menos, diariamente con un retraso máximo de 24 horas.
| Métrica de eventos | Volumen y frecuencia de los eventos | Descripción |
|---|---|---|
Volumen de eventos de search |
100,000 búsquedas |
Se requieren al menos 100,000 búsquedas para optimizar la experiencia de búsqueda en función de los eventos transferidos. |
Objeto search mínimo requerido
En los siguientes ejemplos, se muestran solo los campos obligatorios del formato del evento de usuario search.
searchQuery para los eventos de búsqueda en los que el usuario ingresó una consulta de texto.
El attributionToken se devuelve con los resultados de la búsqueda.
El objeto
documents
contiene el ID del documento
(id) y su nombre de
recurso (name).
- Cuando transfieres o registras eventos de usuario a nivel del almacén de datos, puedes proporcionar
el ID del documento (
id) o el nombre del recurso (name). - Cuando transfieres o registras eventos a nivel de ubicación, debes proporcionar el
nombre del recurso del documento (
name) porque indica la ruta de acceso completa de un documento y hace referencia al almacén de datos en el que reside el documento. Puedes proporcionar el ID del documento como información adicional opcional.
JavaScript Pixel
var user_event = {
"eventType": "search",
"userPseudoId": "USER_PSEUDO_ID",
"engine": "APP_ID",
"eventTime": "2020-01-01T03:33:33.000001Z",
"searchInfo": {
"searchQuery": "SEARCH_QUERY",
},
"attributionToken": "ATTRIBUTION_TOKEN",
"documents": [
{
"name": "DOCUMENT_NAME_1",
},
{
"name": "DOCUMENT_NAME_2",
},
]
};
BigQuery
Este es el esquema JSON completo para este tipo de evento de usuario. Especifica este esquema cuando crees tablas para este tipo de evento de usuario en BigQuery.
Los modos de los campos obligatorios se establecen en REQUIRED o REPEATED. Los modos para
los campos opcionales se establecen en NULLABLE.
Ten en cuenta que se requiere eventTime para importar eventos con
BigQuery. eventTime es una cadena con un formato de marca de tiempo.
[ { "name": "eventType", "type": "STRING", "mode": "REQUIRED" }, { "name": "userPseudoId", "type": "STRING", "mode": "REQUIRED" }, { "name": "engine", "type": "STRING", "mode": "NULLABLE" }, { "name": "eventTime", "type": "STRING", "mode": "REQUIRED" }, { "name": "searchInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "searchQuery", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "pageInfo", "type": "RECORD", "mode": "NULLABLE", "fields": [ { "name": "pageCategory", "type": "STRING", "mode": "NULLABLE" } ] }, { "name": "attributionToken", "type": "STRING", "mode": "NULLABLE" }, { "name": "documents", "type": "RECORD", "mode": "REPEATED", "fields": [ { "name": "id", "type": "STRING", "mode": "NULLABLE" } ] } ]
Acerca de la información del usuario
userPseudoId representa el identificador de usuario único y es obligatorio cuando registras un evento del usuario.
La información del usuario ([UserInfo][user-info]) que se incluye cuando registras un evento de usuario contiene el valor userPseudoId y, si está disponible, el valor userId.
userId es opcional y se puede usar como un identificador único y persistente para un
usuario en todos los dispositivos cada vez que este se conecta a tu sitio. Cuando registras el userId de un usuario, las apps de Gemini Enterprise pueden generar resultados más personalizados para un usuario en varios dispositivos, como un dispositivo móvil y un navegador web.
Acerca de la marca de tiempo
Cuando registres un evento del usuario, asegúrate de incluir una marca de tiempo precisa de cuándo ocurrió el evento. Las marcas de tiempo precisas garantizan que tus eventos se almacenen en
el orden correcto. Las marcas de tiempo se registran automáticamente para los eventos recopilados
con el píxel de JavaScript. Cuando importas eventos, debes proporcionar la
marca de tiempo en el campo [eventTime][event-time] en el formato que especifica RFC
3339.
[rec-type-reqs]: /gemini/enterprise/docs/about-media-recommendations-types [record-events]: /gemini/enterprise/docs/record-user-events [event-time]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents#UserEvent.FIELDS.event_time [user-event]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents [user-info]: /gemini/enterprise/docs/reference/rest/v1/projects.locations.dataStores.userEvents#userinfo