Referencia de la API de Eventos

La API de Eventos de Hotjar te permite enviar eventos a Hotjar utilizando JavaScript cuando se producen acciones específicas en tu sitio, guardándolos dentro de Hotjar como Eventos. Estos eventos se pueden utilizar para ayudarte a filtrar los datos de Grabaciones y Mapas de calor, y para disparar la captura de sesión para iniciar o hacer que aparezcan los widgets de Comentarios y Encuestas. 

• Resumen
• La llamada a la API de Eventos
• Ejemplos de llamadas a la API de Eventos
• Mejores prácticas
• Pruebas de Eventos

---

Resumen

Los Eventos de Hotjar representan las acciones que un usuario realiza en tu sitio. Estos eventos se definen y se envían a Hotjar a través del código del lado del cliente utilizando la API de Eventos de Hotjar. Esta API está disponible en todas las páginas que contienen el Código de Seguimiento de Hotjar.

Con JavaScript, puedes establecer tus propios criterios para determinar qué tipo de acción genera el envío de un evento a Hotjar. El evento puede enviarse tan pronto como se carga la página, cuando aparece un modal o cuando se ve una variación específica del contenido a través de una prueba A/B.

Por ejemplo, puede ser útil realizar un seguimiento de los usuarios que han agregado correctamente una tarjeta de crédito durante el proceso de pago agregando un evento como Tarjeta de crédito agregada correctamente. También puede interesarte comparar las sesiones en las que no se agregó correctamente una tarjeta de crédito agregando un segundo evento, como Error al agregar tarjeta de crédito. Al pasar eventos basados en las acciones del usuario, puedes filtrar las Grabaciones por usuarios que hayan activado cada tipo de evento durante su proceso de pago. La configuración de estos eventos en el código de tu sitio puede verse similar a esto:

fetch('/api/add-credit-card', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
})
.then((response) => response.json())
.then((data) => {
    hj('event', 'Tarjeta de crédito agregada correctamente')
    // manejar la respuesta del backend.
  }
)
.catch(error => {
  hj('event', 'Error al agregar tarjeta de crédito')
})

*Consulta a tus propios desarrolladores para determinar qué código será necesario para tu sitio.

Dado que los criterios para enviar eventos se basan en tu propio código, esta función es muy flexible pero requerirá programación personalizada por parte de tu desarrollador web.

Volver arriba

La llamada a la API de Eventos

A continuación se muestra el formato básico para realizar una llamada a la API de Eventos:

hj('event', 'nombre_de_la_acción');

• El primer parámetro siempre debe contener el valor de cadena evento.
• El segundo parámetro es el nombre personalizado asignado a tu evento. En el ejemplo anterior, el nombre del evento es nombre_de_accion, pero puede ser cualquier cosa que elijas. (Ejemplo: 'modal_abierto', 'variante_a_mostrada', etc.)

Ten en cuenta las limitaciones al implementar eventos

• Nombrar tus eventos.

  El nombre del evento no debe exceder los 250 caracteres y solo puede contener cualquiera de los siguientes: caracteres alfanuméricos (a-z, A-Z, 0-9), espacios, guiones bajos (_), guiones (-), puntos (.), dos puntos (:) y barras diagonales (/).

• Hay un límite de 10,000 eventos únicos por sitio de Hotjar.

  Los filtros de Hotjar solo admitirán 10,000 eventos únicos por sitio de Hotjar, con un número ilimitado de usuarios asociados a esos eventos. Si superas este límite, solo se podrán buscar en la interfaz los 10,000 eventos más utilizados (ordenados de 0-9, a-Z). Este es un total acumulativo, por lo que una vez que se excede el límite, algunos eventos existentes pueden dejar de ser buscables en el filtro. Si superas el límite, puedes eliminar grabaciones que contengan eventos que ya no necesitas. Alrededor de 10 minutos después de la eliminación, se actualizará la lista de filtros de eventos.

• Solo los primeros 50 eventos únicos en una sola sesión serán buscables mediante filtros.
  Para optimizar el rendimiento, Hotjar solo evaluará los primeros 50 eventos únicos en una sesión al determinar si una sesión coincide con los criterios de filtro de eventos. Esto significa que si una sesión contiene 51 eventos únicos, el último evento único que se activó durante la sesión no se detectará si filtras las grabaciones en función de ese evento. Sin embargo, los 51 eventos seguirán siendo visibles en la vista de reproducción de grabaciones de cada sesión.

• Actualmente no es posible pasar ninguna propiedad de evento con el evento.

Volver arriba

Ejemplos de llamadas a la API de eventos

A continuación se muestran algunos casos de uso de ejemplo para eventos.

• Envía un evento a Hotjar que puedes usar para activar una encuesta cuando un usuario hace clic en un botón de suscripción.

  hj('event', 'suscribirse_a_lista_de_correo');
  

• Envía un evento a Hotjar relacionado con un error específico, para que puedas filtrar tus grabaciones por usuarios que encontraron un error durante su sesión.

  hj('event', 'error_ocurrido');
  

• Envía un evento a Hotjar para que sepas cuándo un usuario carga una variante de página específica durante una prueba A/B.

  hj('event', 'variante_b_mostrada');

Volver arriba

Mejores prácticas

• No pase información de identificación personal como un evento.

  La información de identificación personal (PII) nunca debe usarse como eventos en Hotjar. Si desea conectar los datos de sesión con usuarios específicos, debe explorar la función de Atributos de usuario en su lugar.

• Si también realiza llamadas a la API de Identificar, estas deben ejecutarse antes de las llamadas a la API de Eventos.

  Es posible que desee combinar Eventos con la segmentación basada en Atributos de usuario para activar Encuestas o Comentarios. Para configurar esto, el orden de ejecución requiere que la llamada a la API de Identificar ocurra antes de la llamada a la API de Eventos, teniendo en cuenta cualquier llamada asíncrona a otros servicios. Si la llamada a la API de Eventos se ejecuta antes de que la llamada a la API de Identificar haya terminado de ejecutarse, el widget de Encuesta o Comentarios no se mostrará.

• Los eventos no se pueden utilizar para recopilar direcciones de correo electrónico o IP, ni números con 9 o más dígitos.

  Dado que actualmente no hay forma de utilizar nuestra herramienta de búsqueda de usuarios con eventos, no se pueden utilizar para recopilar correos electrónicos, direcciones IP o números con 9 o más dígitos para evitar que se transmitan números de tarjetas de crédito a Hotjar. Esta decisión se ha basado en el Reglamento General de Protección de Datos (GDPR). Si desea recopilar direcciones de correo electrónico con el consentimiento de su usuario y de acuerdo con el GDPR, puede hacerlo con Atributos de usuario.

• El código de seguimiento de Hotjar debe cargarse antes de enviar cualquier evento.

  No se puede acceder al objeto hj() hasta que el código de seguimiento de Hotjar se haya ejecutado en la página. Si el script que llama a la API de Eventos se agrega antes de su código de seguimiento de Hotjar, se producirá un error y el evento no se reconocerá. Si por alguna razón se accede a la API de Eventos antes de que se haya ejecutado el código de seguimiento de Hotjar, puede agregar la siguiente línea de código antes de llamar al código de la API de Eventos:

  window.hj=window.hj||function(){(hj.q=hj.q||[]).push(arguments);};

• Para sitios de comercio electrónico, evite enviar información de productos específicos.

  Esto incluye información como códigos SKU. Por lo general, las URL son más útiles y se capturan automáticamente.

• Tenga cuidado al enviar valores de objetos como capas de datos de GTM.

  A menudo, estos contienen más datos de los que espera.

• Evite pasar cualquier cosa como fechas o marcas de tiempo.
• Evite pasar cualquier cosa desde URL, como códigos de referencia.
• Evite pasar registros de errores detallados.

Volver arriba

Pruebas de eventos

Los siguientes pasos le permitirán confirmar si las llamadas a la API de Eventos se reciben correctamente en Hotjar. Si no está familiarizado con la consola del navegador o las herramientas de desarrollo, considere la posibilidad de involucrar a un miembro del equipo que tenga más conocimientos sobre estas herramientas o a un desarrollador web para que le ayude.

Habilitar los registros de depuración de Hotjar en la consola del navegador.

Abra la página donde desea probar el evento y agregue el parámetro ?hjDebug=1 al final de la URL. Aquí hay un par de ejemplos de cómo podría verse:

https://www.example.com/?hjDebug=1
OR
https://www.example.com/?utm_1234&hjDebug=1

Abre la consola de tu navegador.

Si no estás familiarizado con las herramientas de desarrollo de tu navegador o con la consola, consulta esta guía para aprender cómo abrir la consola de tu navegador.

Dispara el evento manualmente.

Para disparar tu evento manualmente, agrega el código de la API de Eventos en la consola de tu navegador y presiona Enter o Return en tu teclado. Si el evento se dispara correctamente, verás un registro de confirmación similar a este:

También te recomendamos que sigas los pasos que seguiría tu usuario para activar el evento automáticamente. Si el evento se dispara automáticamente, sabrás que tu código se ha implementado correctamente.

Si se detecta el mismo evento al dispararlo manualmente, pero no automáticamente al probar el recorrido del usuario, es posible que debas revisar tu código y los criterios que determinan cuándo se envía la llamada de la API de Eventos.

Volver arriba