Acerca de los eventos de usuario

.

En esta página se describen los eventos de usuario de las aplicaciones de búsqueda personalizada y de recomendaciones, incluidos los tipos de eventos de usuario, los requisitos y ejemplos de tipos de eventos de usuario.

Aunque no es obligatorio usar eventos de usuario en las aplicaciones personalizadas, es muy recomendable hacerlo.

Te recomendamos que subas eventos al menos una vez al día para mantener una buena calidad de los datos. Durante las importaciones de eventos históricos, asegúrese de que la distribución de los datos se incline hacia la marca de tiempo más reciente. El número de eventos del último día con marca de tiempo debe ser igual o superior al recuento medio de eventos diarios.

Para obtener ayuda sobre cómo registrar eventos de usuario, consulte Registrar eventos de usuario en tiempo real. Para importar eventos de usuario anteriores en bloque, consulte Importar historial de eventos de usuario.

Tipos de eventos de usuario

Puede registrar los siguientes tipos de eventos de usuario mientras los usuarios finales navegan o buscan en su sitio:

Nombre del evento de usuario Acción de usuario
view-item-list Muestra un panel o una lista ordenada de documentos.
view-item Muestra los detalles de un documento.
view-home-page Ve la página principal.
search Busca en el almacén de datos.

Para obtener información sobre el objeto de evento de usuario, consulta la documentación de referencia de la API UserEvent.

Ejemplos y esquemas de tipos de eventos de usuario

En esta sección se proporcionan los formatos de datos de cada tipo de evento admitido por las aplicaciones personalizadas. Se proporcionan ejemplos de píxel de JavaScript. En el caso de BigQuery, se proporciona el esquema de tabla completo de cada tipo.

En todos los tipos de eventos de usuario, userId es opcional.

Ten en cuenta que:

  • El campo tagIds solo es necesario si estás llevando a cabo un experimento A/B.

  • El campo attributionToken es opcional y se usa para medir el rendimiento. Los eventos search y view-item que se generen a partir de clics en recomendaciones deben tener un token de atribución para vincular los eventos a las recomendaciones que los han generado.

Para obtener más información sobre el objeto de evento de usuario, consulta la documentación de referencia de la API UserEvent.

view-item

A continuación, se muestra el formato de los datos de eventos de usuario view-item.

Requisitos de optimización de la búsqueda para eventos view_item

Para que la 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 deben subirse al menos una vez al día, con un retraso máximo de 24 horas.

Métrica de eventos Volumen o frecuencia de eventos Descripción
Volumen de eventos de view-item 250.000 elementos de vista

Se necesitan al menos 250.000 elementos de vista para optimizar la experiencia de búsqueda en función de los eventos registrados.

Objeto view-item mínimo requerido

En los siguientes ejemplos solo se muestran los campos obligatorios del formato de evento de usuario view-item.

En la mayoría de los casos, documents contiene detalles sobre el documento asociado.

Píxel de JavaScript

var user_event = {
  "eventType": "view-item",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
  "documents": [{
    "id": "document-id"
  }]
};

BigQuery

Este es el esquema JSON completo de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios se definen como REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con formato de marca de tiempo. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "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"
          }
        ]
      }
    ]
  }
]

view-home-page

A continuación, se muestra el formato de evento de usuario view-home-page.

Objeto view-home-page mínimo requerido

En los siguientes ejemplos solo se muestran los campos obligatorios del formato de evento de usuario view-home-page.

Píxel de JavaScript

var user_event = {
  "eventType": "view-home-page",
  "userPseudoId": "user-pseudo-id",
  "eventTime": "2020-01-01T03:33:33.000001Z",
};

BigQuery

Este es el esquema JSON completo de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios se definen como REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con formato de marca de tiempo. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "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": "quantity",
        "type": "INT64",
        "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"
          }
        ]
      }
    ]
  }
]

A continuación, se muestra el formato de evento de usuario search.

Requisitos de optimización de la búsqueda para eventos de búsqueda

Para permitir que la 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 deben subirse al menos una vez al día, con un retraso máximo de 24 horas.

Métrica de eventos Volumen o frecuencia de eventos Descripción
Volumen de eventos de search 100.000 búsquedas

Se necesitan al menos 100.000 búsquedas para optimizar la experiencia de búsqueda en función de los eventos registrados.

Objeto de búsqueda mínimo requerido

En los siguientes ejemplos solo se muestran los campos obligatorios del formato del evento de usuario search.

Se requiere al menos uno de los campos searchQuery o pageCategory:

  • Proporciona searchQuery para los eventos de búsqueda en los que el usuario haya introducido una consulta de texto.

  • Proporciona pageCategory cuando el usuario haya accedido a los elementos de interés navegando, es decir, haciendo clic en categorías en lugar de introducir una consulta de texto.

El attributionToken se devuelve con la consulta de búsqueda o los resultados de navegación.

documents debe incluir la lista de IDs de documentos que se muestran al usuario final en la página de resultados de búsqueda.

Píxel de JavaScript

var user_event = {
  eventType: "search",
  userPseudoId: "user-pseudo-id",
  eventTime: "2020-01-01T03:33:33.000001Z",
  searchInfo: {
    searchQuery: "search-query",
  }, 
  pageInfo: {
    pageCategory: "category1 > category2",
  }, 
  attributionToken: "attribution-token",
  documents: [
    {
      id: "document-id1",
    },
    {
      id: "document-id2",
    },
  ]
};

BigQuery

Este es el esquema JSON completo de este tipo de evento de usuario. Especifique este esquema al crear tablas para este tipo de evento de usuario en BigQuery.

Los modos de los campos obligatorios se definen como REQUIRED o REPEATED. Los modos de los campos opcionales se definen como NULLABLE.

Tenga en cuenta que eventTime es obligatorio para importar eventos con BigQuery. eventTime es una cadena con formato Timestamp. 

[
  {
    "name": "eventType",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "userPseudoId",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "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 de usuario

userPseudoId representa el identificador de usuario único y es obligatorio cuando registra un evento de usuario.

La información de usuario (UserInfo) que se incluye al registrar un evento de usuario contiene el valor userPseudoId y, si está disponible, el valor userId. userId es opcional y se puede usar como identificador único y persistente de un usuario en varios dispositivos cada vez que inicie sesión en su sitio. Cuando registras el userId de un usuario, tus aplicaciones de búsqueda y recomendación 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 registre un evento de usuario, asegúrese de incluir una marca de tiempo precisa de cuándo se produjo el evento. Las marcas de tiempo precisas aseguran que los eventos se almacenen en el orden correcto. Las marcas de tiempo se registran automáticamente en los eventos recogidos mediante el píxel de JavaScript. Cuando importe eventos, debe proporcionar la marca de tiempo en el campo eventTime con el formato especificado en RFC 3339.

Siguientes pasos