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 que las aplicaciones personalizadas tengan eventos de usuario, es muy recomendable que los incluyan.

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
add-feedback Añade comentarios de los usuarios.
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.

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 son 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": "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 del 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 son 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": "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 del evento de usuario search.

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 son 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 tus 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