Identificar Referencia de API

La API de Identificación de Hotjar te permite enviar datos sobre tus usuarios a Hotjar utilizando Javascript, guardándolos como Atributos de usuario. Estos Atributos de usuario pueden ser utilizados por Hotjar para habilitar filtros y segmentaciones avanzadas, brindándote información de calidad más rápido que antes. Puedes enviar hasta 100 atributos de usuario en cualquier sitio, con cualquier cantidad de usuarios asociados a esos atributos.

Los Atributos de usuario se pueden utilizar para filtrar Grabaciones y dirigir Encuestas y widgets de Comentarios, así como para realizar solicitudes de búsqueda y eliminación de usuarios por ID de usuario.

Sigue los enlaces a continuación para obtener más información sobre los Atributos de usuario:

• Visión general
• Manejo de IDs de usuario
• Realizar llamadas a Identify
• Valores de Atributos de usuario
• Manejo de direcciones de correo electrónico
• Ejemplos de cómo pasar Atributos de usuario a Hotjar
• Uso de la API de Identificación de manera legalmente conforme
• Desactivar Atributos de usuario
• Eliminar Atributos de usuario
• Mejores prácticas
• Preguntas frecuentes

---

Visión general

Los Atributos de Usuario son valores de datos sobre los usuarios de su sitio que se envían a Hotjar desde su código del lado del cliente a través de la API de Identificación de Hotjar. Esta API está disponible en todas las páginas que contienen el Código de Seguimiento de Hotjar.

Estos datos se envían a Hotjar en pares clave-valor como una llamada AJAX asíncrona a los servidores de Hotjar. Estos valores están asociados con un ID de Usuario, un valor único identificable que se envía a Hotjar en su código desde un valor de ID de Usuario de su base de datos de usuarios. Esto permite a Hotjar asociar los datos recopilados sobre ellos con el mismo ID de usuario que utiliza en su propia base de datos, así como buscar información de usuario que Hotjar tenga sobre ese usuario.

Hay 4 fases en el proceso de enviar Atributos de Usuario a Hotjar y utilizarlos con Hotjar.

1. Obtener los datos de su sitio.
2. Pasar los datos a Hotjar a través de la API de Identificación.
3. Hotjar almacena los datos sobre cada usuario como Atributos de Usuario asociados a su user_id.
4. Ahora puede utilizar las herramientas de Hotjar para dirigirse y filtrar por Atributos de Usuario.

Volver arriba

Realizar llamadas a Identificar

Antes de poder comenzar a realizar llamadas a Identificar, los Atributos de Usuario deben estar habilitados en la configuración de Hotjar para cada sitio con el que desee utilizar Atributos de Usuario.

Habilitar y deshabilitar Atributos de Usuario

La capacidad de acceder a la API de Identificación y a los Atributos de Usuario estará habilitada de forma predeterminada si esta función está incluida en su plan de Hotjar. Sin embargo, si los Atributos de Usuario estaban deshabilitados en el pasado, es posible que necesite habilitarlos nuevamente para su uso.

En su página de Atributos de Usuario (Configuración > Atributos de Usuario), encuentre el Sitio al que desea agregar Atributos de Usuario utilizando el menú desplegable de selección. Verá algo como esto que muestra el estado de la implementación de sus Atributos de Usuario:

También puede deshabilitar los Atributos de Usuario en esta página. Una vez que haya seleccionado un Sitio con los Atributos de Usuario habilitados, haga clic en Deshabilitar Atributos de Usuario. Una vez que haya hecho esto, las futuras llamadas a la API serán bloqueadas. El botón "Deshabilitar Atributos de Usuario" solo aparecerá después de que Hotjar haya recibido los datos de atributos de usuario, pero no antes.

Cualquier informe que dependa de los Atributos de Usuario con fines de segmentación se desactivará, y no podrá volver a habilitarlos a menos que cambie sus opciones de segmentación o vuelva a habilitar los Atributos de Usuario.

Si desea evitar que se envíen Atributos de Usuario en el futuro, debe eliminar el código de la API de Identificación de su sitio. Una vez que se elimine el código de su sitio, los Atributos de Usuario recopilados anteriormente seguirán existiendo, pero ya no se actualizarán ni se agregarán a los nuevos usuarios de su sitio.

La llamada a la API

Este es el formato para una llamada a la API de Identificación:

hj('identify', userId, { 
    user_attribute: value
});

• El primer parámetro siempre debe contener el valor de cadena "identify".
• El segundo debe ser una cadena que contenga el ID de usuario para un usuario en su sitio, de su propia base de datos de usuarios, o nulo si no se conoce.
• El tercero es una serie de pares clave-valor dentro de un objeto. La clave proporciona el nombre del Atributo de Usuario, y el valor define tanto el tipo de Atributo de Usuario como su valor para ese usuario.

Los valores pasados a esta llamada deben provenir de la base de código de su propio sitio. Estos valores podrían ser extraídos directamente de sus servidores o generados del lado del cliente.

Una vez enviados a Hotjar, estos atributos y los valores para cada usuario se almacenan en los servidores de Hotjar. Cada vez que se realiza una llamada a Identify, los valores almacenados en los servidores de Hotjar se reemplazarán con los valores más recientes para estos atributos.

Usted puede consultar todos los atributos enviados a Hotjar en la página de configuración de Atributos de Usuario. Puede utilizar la función de Búsqueda de Usuario para inspeccionar qué valores se han pasado para un usuario específico en su sitio.

Mientras un usuario esté identificado durante su sesión, Hotjar podrá asociar tanto IDs de Usuario como Atributos de Usuario con la Grabación de una sesión, y ofrecer una segmentación precisa del widget de Feedback, permitiéndole recopilar comentarios específicos de usuarios utilizando Feedback y Encuestas. Por ejemplo: "Quiero que esta Encuesta se dirija únicamente a los clientes que han realizado una compra hace más de 10 días".

Volver arriba

Manejo de IDs de Usuario

El segundo argumento pasado a Hotjar a través de la llamada de la API Identify debe ser un ID de usuario único e identificable de la base de datos de su propio sitio. Los Atributos de Usuario están asociados con este ID de Usuario.

El ID de Usuario debe ser único por usuario pero no debe contener información personal en sí mismo. También debe ser un valor que nunca cambie para este usuario. Una vez que haya establecido un ID de Usuario en Hotjar, no se puede cambiar. Si cambia, Hotjar considerará que se trata de un usuario totalmente nuevo.

Si se conoce un ID de Usuario, el ID de Hotjar del usuario se asociará con su ID de Usuario. Un ID de Hotjar es un ID de usuario único generado aleatoriamente, creado a nivel del Sitio de Hotjar. Si un usuario no tiene un ID de Usuario cuando visita un sitio inicialmente, entonces el ID de Hotjar se asociará con su ID de Usuario una vez que se realice la llamada a la API Identify con un ID de Usuario.

Es útil trabajar esto con un ejemplo.

Imaginemos que tenemos a una usuaria, Rachel. Ella visita el sitio 3 veces en 2 dispositivos diferentes.

• Sesión A - Rachel visita radbooks.com en su tablet.
  • No es una usuaria del sitio aún y se le asigna un ID de Hotjar 123
• Sesión B - Rachel luego visita el sitio en su móvil.
  • No es una usuaria aún y se le asigna un ID de Hotjar 456
• Sesión C - Rachel regresa al sitio desde su móvil.
  • Hotjar la reconoce con el ID de Hotjar 456.
  • Luego registra una cuenta.
  • Su llamada a Identify le asigna un ID de Usuario de ABC, utilizando el mismo ID de Usuario que tienes para ella en tu base de datos.

Como la hemos asociado con un ID de Usuario en tu sitio, luego conectamos todos los datos asociados con el ID de Hotjar 456 con su ID de Usuario de ABC, aunque no haya iniciado sesión durante la Sesión B.

Si Rachel luego visita el sitio en su tablet en una cuarta sesión, y esta vez inicia sesión, Hotjar unirá los datos de la Sesión A, B y C, dándote una imagen completa de sus interacciones con tu sitio.

¿Qué sucede si no tienes un ID de Usuario?

Si el ID de Usuario no se conoce, entonces debes pasar un valor de null como segundo parámetro. Cuando haces esto, cualquier Atributo de Usuario pasado a la API de Identify se asociará con el ID de Hotjar del usuario en su lugar.

Valores de Atributos de Usuario

Puedes pasar los siguientes valores a una clave de Atributo de Usuario utilizando la API de Identify. Los caracteres especiales no pueden ser utilizados en este momento.

Tipo	Valores	Limitaciones/Notas
Número	Enteros o decimales	Mínimo: -9007199254740991 Máximo: 9007199254740991
Cadenas	Texto	Máximo de 200 caracteres No distingue entre mayúsculas y minúsculas Compatible con UTF-8 No enviar direcciones de correo electrónico
Fecha	Cadenas de fecha ISO-8601	Desde JavaScript, utiliza la función toISOString() en un objeto de fecha.
Booleano	valores true o false

Manejo de direcciones de correo electrónico

Actualmente, hay una clave de Atributo de Usuario para direcciones de correo electrónico: email. Las direcciones de correo electrónico deben pasarse como cadenas a email. Por ejemplo:

hj('identify', userId, {
	email: 'test@test.com' 
});

Si algún otro Atributo de Usuario de tipo cadena contiene una dirección de correo electrónico, estos serán rechazados, lo que significa que solo debes usar `email` para pasar direcciones de correo electrónico.

Ejemplos de pasar Atributos de Usuario a Hotjar

Identificar clientes que pagan

Aquí hay un ejemplo, donde queremos decirle a Hotjar cuánto dinero ha gastado alguien en su sitio.

hj('identify', userId, {
	total_spend: 500
});

Se pueden pasar múltiples atributos agregando más pares clave-valor al objeto. ¿Quizás quería que Hotjar supiera cuándo se convirtieron en cliente por primera vez?

hj('identify', userId, {      
	total_spend: 500,
	first_purchase: '2019-06-20Z'
});

Aquí le estamos diciendo a Hotjar que su usuario se convirtió en cliente de su servicio utilizando una cadena de fecha ISO8601.

Identificar Atributos para Usuarios Desidentificados

A veces es útil rastrear información sobre usuarios en su sitio, incluso si aún no son usuarios o clientes que pagan. Digamos que quería rastrear la fuente de referencia y la variante de prueba A-B de la página de destino desde la que un posible cliente potencial llegó a usted:

hj('identify', null, {
    ab_test: 'variante-A',
    referrer: 'facebook_paid'
});

Esto sería útil si quisiera dirigir una encuesta a los usuarios en la variante-A, o solo a aquellos que llegaron a usted desde anuncios pagados de Facebook, por ejemplo.

Uso del API Identify de manera legalmente conforme

El API Identify está desactivado de forma predeterminada, lo que facilita evitar capturar accidentalmente información personal hasta que haya manejado adecuadamente las preocupaciones de privacidad. Al habilitar Atributos de Usuario, es posible que esté pasando los datos personales de sus usuarios finales a Hotjar. Requerimos que reconozca sus obligaciones legales al hacerlo y acepte el Acuerdo de Procesamiento de Datos de Hotjar.

Es su responsabilidad utilizar esta función de manera legalmente conforme, de acuerdo con las leyes de su país y los países que visitan sus usuarios. Visite nuestra página de privacidad para obtener más información sobre el enfoque de Hotjar hacia la privacidad del usuario. Al utilizar Atributos de Usuario, debe ser consciente y cumplir con los Términos de Servicio y la Política de Uso Aceptable de Hotjar.

Volver arriba

Manejo de Solicitudes de Búsqueda y Eliminación de Usuario

Es posible buscar y eliminar los datos de un usuario utilizando su ID de usuario. Obtenga más información al respecto en nuestro artículo "Cómo utilizar la Búsqueda de Usuario". Es importante tener en cuenta que si conoce el ID de usuario de un usuario y su dirección de correo electrónico, debería buscar su información con ambos. Esta es la única forma de asegurarse de que toda la información personal que Hotjar tiene sobre este usuario haya sido buscada y eliminada.

html

Volver arriba

Desactivación de Atributos de Usuario

Para evitar que se envíen más Atributos de Usuario a Hotjar, debes desactivar los Atributos de Usuario.

Mientras los Atributos de Usuario estén habilitados en tu sitio, si deseas evitar que se envíen en el futuro, debes eliminar el código en tu sitio que los envía a Hotjar. Una vez que se elimine el código de tu sitio, los Atributos de Usuario recopilados anteriormente seguirán existiendo, aunque ya no se actualizarán ni se agregarán a nuevos usuarios en tu sitio.

Volver arriba

Eliminación de Atributos de Usuario

Los Atributos de Usuario se pueden eliminar desde la página de gestión de Atributos de Usuario haciendo clic en el icono de papelera a la derecha del atributo. Solo los miembros del equipo con permisos de 'Leer y Escribir' o superiores pueden eliminar Atributos de Usuario.

Cuando se elimina un atributo, desaparecerá inmediatamente de la aplicación de Hotjar. Sin embargo, el atributo aún se almacena en el backend durante 7 días antes de ser eliminado permanentemente. Los datos asociados con el atributo se ignoran durante el período de 7 días. Esto se hace para evitar que se envíen datos debido a problemas de almacenamiento en caché.

Si deseas volver a crear un atributo que fue eliminado, deberás esperar 7 días antes de que el atributo pueda ser recreado con éxito.

Volver arriba

Mejores Prácticas

Cuándo realizar llamadas a la API de Identificación

Debes realizar llamadas a Identificación cada vez que:

• Se carga una página con los valores más recientes (incluso si no han cambiado).
• Después de un cambio de URL en aplicaciones de una sola página.
• Cada vez que se realiza un cambio. Por ejemplo, si deseas rastrear su última compra en una tienda, querrás actualizar este atributo de usuario una vez que se haya realizado la compra.

Cada llamada actualizará los Atributos de Usuario en Hotjar con los valores más recientes. Cuando una grabación de sesión finaliza, la grabación guarda los valores más recientes en el momento en que finaliza la sesión. Cuando se realiza una llamada, pero los valores no se han actualizado, la solicitud de red no se enviará para evitar solicitudes AJAX innecesarias.

Combinar llamadas a la API de Identificación con disparadores para segmentar Encuestas/Widgets de Retroalimentación

Si planeas combinar Eventos con la segmentación de Atributos de Usuario para Encuestas o Widgets de Retroalimentación, debes asegurarte de que la llamada a Identificación haya ocurrido antes del disparador en tu orden de ejecución, teniendo en cuenta cualquier llamada asincrónica a otros servicios. Si el disparador se ejecuta antes de que la llamada a la API de Identificación haya finalizado, el widget de Encuesta/Retroalimentación no se mostrará.

Cola de llamadas a la API antes de que Hotjar se haya cargado

Si este script se agrega antes de tu código de seguimiento de Hotjar, se producirá un error.

El objeto hj() no se puede acceder hasta que se haya ejecutado la etiqueta de código de seguimiento de Hotjar. Si por alguna razón accedes a la API de Identificación antes de que se haya ejecutado el código de seguimiento, puedes agregar la siguiente línea de código antes de llamar a la API:

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

Prueba de Atributos de Usuario

Hay algunas formas de probar si los Atributos de Usuario se están enviando correctamente a través de la API de Identificación.

• Una vez que el código esté activo en tu página y se haya activado al menos una vez, puedes visitar la página de configuración de Atributos de Usuario para ver si el Atributo de Usuario capturado por Hotjar está activo en tu página.
• Puedes habilitar el modo de depuración de Hotjar en tu navegador para ver si las llamadas a la API de Identificación se están enviando correctamente a Hotjar durante tu sesión.
• Para usuarios con valor nulo, puedes utilizar cualquier dirección de correo electrónico que poseas para consentir en conectar respuestas de Retroalimentación a través de una Encuesta o Retroalimentación. Esto te permitirá ver qué Atributos de Usuario se están pasando a usuarios no identificados, lo cual es especialmente útil para verificar que no estás enviando accidentalmente información de identificación personal a Hotjar. Es importante tener en cuenta que los usuarios que no han consentido en conectar Retroalimentación no pueden ser buscados de esta manera, por lo que, para fines de prueba, debes configurar un widget de retroalimentación para otorgar consentimiento con tu propia dirección de correo electrónico.

Volver arriba