Referencia de la API de eventos

La API de Eventos de Hotjar le permite enviar eventos a Hotjar usando JavaScript cuando acciones específicas tienen lugar en su sitio, guardándolos dentro de Hotjar como Eventos. Estos eventos se pueden utilizar para ayudarle a filtrar las Recordings recopiladas y los datos del Heatmap, y para activar la captura de sesiones para iniciar o para que aparezcan los widgets de Feedback y Surveys.

• Visión general
• La llamada a la API de eventos
• Ejemplos de llamadas a la API de eventos
• Mejores prácticas
• Prueba de eventos

Visión general

Los Eventos Hotjar representan acciones que un usuario ha realizado mientras estaba en su sitio. Estos eventos son definidos y pasados a Hotjar a través de su código del lado del cliente vía la API de Eventos de Hotjar. Esta API está disponible en todas las páginas que contienen el código de Hotjar de Hotjar.

Con JavaScript, usted es capaz de establecer sus propios criterios para determinar qué tipo de acción resulta en un evento que se envía a Hotjar. El evento podría enviarse en cuanto se carga la página, cuando los usuarios hacen clic en un determinado botón, o cuando ven 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 hecho clic en un botón CTA con un evento. Tal vez usted está interesado en diagnosticar por qué la gente no está haciendo clic en él. Al pasar un evento, puede filtrar las Recordings por los usuarios que no han hecho clic en su llamada a la acción. La configuración de esto en el código de su sitio podría ser algo como esto:

document.querySelector('#mi-boton')
	.addEventListener('click', () => hj('event', 'clicked_cta'));

Dado que los criterios para el envío de eventos se basa en su propio código, la característica es muy flexible, pero puede requerir la codificación personalizada de su desarrollador web.

Volver arriba

La llamada a la API de Eventos

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

hj('evento', 'nombre_accion');

• El primer parámetro debe contener siempre el valor de cadena event.
• El segundo parámetro es el nombre personalizado asignado al evento. En el ejemplo anterior, el nombre del evento es nombre_acción, pero puede ser cualquier cosa que elija. (Ejemplo: 'cta_click', 'opened_modal', 'shown_variant_a', etc.)

Tenga en cuenta las limitaciones a la hora de implementar eventos

• Nombre de sus eventos.

  El nombre del evento no debe superar los 250 caracteres y sólo puede contener caracteres alfanuméricos (a-z, A-Z, 0-9), guiones bajos (_) y guiones (-).

• Hay un límite de 10.000 eventos únicos por sitio Hotjar.

  Los Filtros Hotjar sólo soportarán 10.000 eventos únicos por sitio Hotjar, con un número ilimitado de usuarios asociados a esos eventos. Si excede este límite, sólo 10.000 de los eventos más utilizados (ordenados 0-9, a-Z) se podrán buscar en la interfaz. Se trata de un total móvil, por lo que, una vez superado el límite, es posible que algunos de los eventos existentes ya no se puedan buscar en el filtro. Si superas el límite, puedes eliminar las Recordings que contengan eventos que ya no necesites. Unos 10 minutos después de la eliminación, la lista del filtro de eventos se actualizará.

• 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 ejemplos de uso de eventos.

• Envíe un evento a Hotjar que pueda utilizar para activar una encuesta cuando un usuario haga clic en un botón Suscribir.

  hj('event', 'subscribed_to_email_list');
  

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

  hj('event', 'error_occurred');
  

• Enviar un evento a Hotjar para que te avise cuando un usuario carga una variante de página específica durante una prueba A/B.

  hj('event', 'variant_b_displayed');

Volver arriba

Buenas 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 quieres conectar datos de sesión con usuarios específicos, deberías explorar la función de Atributos de Usuario.

• Si también estás haciendo llamadas a la API de Identificación, estas deben ser ejecutadas 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 Surveys o Feedback. Para configurar esto, el orden de ejecución requiere que la llamada a la API de identificación se realice antes que 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 identificación haya finalizado, no se mostrará el widget de encuesta o respuesta.

• 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 pasen 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 en línea con GDPR, puede hacerlo con User Attributes.

• El código de Hotjar necesita cargarse antes de enviar cualquier Evento.

  No se puede acceder al objeto hj( ) hasta que el código de Hotjar se haya ejecutado en la página. Si el script que llama a la API de Eventos es agregado antes que su código de Hotjar, habrá un error y el evento no será reconocido. Si por alguna razón la API de Eventos está siendo accedida antes de que el código de Hotjar se haya ejecutado, entonces puede agregar la siguiente línea de código antes de que el código de la API de Eventos sea llamado:

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

• En los sitios de comercio electrónico, evite enviar información específica sobre los productos.

  Esto incluye información como los códigos SKU. Normalmente, las URL son más útiles y se capturan por defecto.

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

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

• Evite pasar datos como fechas o marcas de tiempo.
• Evite pasar datos de URL como códigos de referencia.
• Evite pasar registros de errores detallados.

Volver arriba

Comprobación de eventos

Siguiendo los siguientes pasos podrá confirmar si sus llamadas a la API de Eventos son recibidas con éxito por Hotjar. Si no está familiarizado con la consola de su navegador o con las herramientas para desarrolladores, considere la posibilidad de recurrir a un miembro del equipo que tenga más conocimientos de estas herramientas o a un desarrollador web para que le ayude.

Habilite los registros de depuración de Hotjar en la consola de su navegador.

Abra la página en la que desea probar el evento y añada el parámetro ?hjDebug=1 al final de la URL. Aquí tienes un par de ejemplos de cómo podría quedar:

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

Abra la consola de su navegador.

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

Lanza el evento manualmente.

Para activar el evento manualmente, añade el código de la API de eventos en la consola del navegador y pulsa Intro o Retorno en el teclado. Si el evento se dispara con éxito, verás un registro de confirmación similar a este:

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

Si el mismo evento se detecta cuando se dispara manualmente, pero no automáticamente cuando se prueba el recorrido del usuario, entonces es posible que tenga que revisar su código y los criterios que determinan cuándo se envía la llamada a la API de eventos.

Volver arriba