Identificación de visitantes

ResumenPunto de finalización
APPLICABLE PRODUCTS
  • Marketing Hub
    • Professional or Enterprise
  • Sales Hub
    • Professional or Enterprise
  • Service Hub
    • Professional or Enterprise
  • Content Hub
    • Professional or Enterprise
 
La API de identificación devisitantes lepermite identificar a los visitantes de su sitio que se autenticaron mediante su propio sistema de autenticaciónexterno . Esta API funciona actualmente en conjunto con la herramienta de chat en vivo de HubSpot. Un token deidentificación devuelto por esta API puede utilizarse para pasar información sobre suvisitanteya autentificado al widget de chat, de modo que éstelo trate como un contacto conocido. Agentes de la bandeja de entrada pueden entonces tener la certeza de con quién están hablando, y los visitantes pueden acceder al historial de conversaciones anteriores en todos los dispositivos.

Nota: esta API no se puede utilizar con bots. 

Caso de uso de ejemplo:
Si alojas tu propia aplicación web tras un inicio de sesión, puedes configurar el widget de chat de HubSpot para que aparezca en las páginas dentro de tu aplicación web donde sabes que los visitantes ya han sido autentificados e identificados. Actualmente, cualquier visitante que chatee en esas páginas seguirá apareciendo como "Visitante desconocido" en la bandeja de entrada de Conversaciones, a pesar de ser un visitante identificado y registrado en su aplicación web. Usando la API de identificación de visitantes, puedes pasar información autenticada del visitante directamente al widget de chat, que los identifica en la bandeja de entrada de conversaciones.
Nota:
- La API de identificación de visitantes sirve para decirle a HubSpot quién es el visitante. No debe confiar en esto para autenticar a los usuarios en su plataforma.
- El acceso a la API de identificación de visitantes requiere una suscripción de nivel profesional o empresarial. Si la cuenta no tiene una suscripción válida, recibirá una respuesta de error 403 de la API.

Flujo de integración de ejemplo

Para integrarte con esta característica, debes tener una aplicación web existente con un sistema de autenticación.
 
Antes de comenzar, asegúrate de tener una aplicación privada configurada y de que la cuenta que intentas integrar tenga una suscripción Pro o Enterprise que cumpla con los requisitos.
 
Este es un ejemplo de un posible flujo de integración:
Posible flujo de identificación del usuario
Una vez que el cliente haya iniciado sesión y haya sido verificado en tu sistema, sigue los pasos a continuación para identificarlo en el chat en vivo.
 

1. En el front-end, configura loadImmediate en false en el objeto hsConversationsSettings en la ventana. Si no haces esto, el widget de chat se puede cargar antes de que se pase la información de identificación.

Consulta el manual del SDK del widget de chat a continuación para obtener más información sobre la API.

Nota: Debes establecer las propiedades hsConversationsSettings fuera de la función isConversationsAPIReady. hsConversationsSettings debe configurarse antes de la llamada, de lo contrario, es posible que experimentes una condición de carrera que interfiera con la carga del widget.

window.hsConversationsSettings = { loadImmediately: false };
2. Genera un token desde la API de identificación de visitantes (consulta la pestaña Puntos de terminación para obtener una solicitud de ejemplo), pasando la dirección de correo electrónico de tu visitante autenticado. Esto debe hacerse en la parte posterior de tu aplicación web.
 
curl --request POST \ --url 'https://api.hubspot.com/conversations/v3/visitor-identification/tokens/create \ --data '{ "email": "gob@bluth.com", "firstName": "Gob", "lastName": "Bluth" }'

El nombre y el apellido proporcionados se establecerán después de que se inicie el chat en el contacto en HubSpot si:

  • Es un nuevo contacto creado por la API de identificación de visitantes
  • Es un contacto existente donde el nombre ya no se conoce

Esto puede ser útil al personalizar mensajes a visitantes identificados cuando tu sistema externo ya tiene información de nombre, pero aún no existe en HubSpot. Se trata de parámetros opcionales y no son obligatorios. 

 

3. Usando el token Paso 2, establece las siguientes propiedades en el objeto hsConversationsSettings en la ventana.

window.hsConversationsSettings = { identificationEmail: "visitor-email@example.com", identificationToken: "<TOKEN FROM STEP 1>" };
4. Carga el widget
window.HubSpotConversations.widget.load();

El token y el correo electrónico deben establecerse en el objeto hsConversationsSettings en la ventana cada vez que se cargue la página para un visitante autenticado. Este contexto no se llevará a través de las cargas de página automáticamente si estos parámetros ya no están establecidos. Los tokens son temporales y caducarán después de 12 horas. Los tokens se pueden almacenar en caché para evitar volver a obtener el token en cada carga de página, siempre y cuando se actualicen al menos cada 12 horas

Verificar la integración

Una vez que hayas completado la integración de la característica de identificación de visitantes, querrás verificar que funciona como se espera.
 
A continuación te detallamos un par de flujos que podrías probar en función de la configuración de tu aplicación específica. Tenemos algunos casos de uso principales, pero es posible que debas adaptarlos a tu caso de uso exacto.
 
Si tienes el widget de chat en una o más páginas públicas, así como detrás de un sistema de autenticación:
 
En primer lugar, navega a una página donde el widget de chat no debería identificar a los visitantes e iniciar una conversación. Entra en la bandeja de entrada de tu portal de HubSpot y comprueba que el chat que acaba de llegar pertenece a un "Visitante desconocido". Si no es el caso, prueba a seguir estos pasos en una ventana de Incógnito o de navegación privada.
 
En segundo lugar, navega a una página donde el widget de chat debería identificar a los visitantes a través de la API de identificación de visitantes e inicia una conversación. A continuación, accede a la Bandeja de entrada de tu portal de HubSpot y comprueba que el chat se atribuye correctamente al contacto con el que iniciaste sesión. Deberías ver una insignia junto al nombre del contacto, indicando que este contacto se identificó correctamente a través de esta API.
visitor_identity_badge
 
Si solo tienes el widget de chat cargado en páginas detrás de un sistema de autenticación y tienes acceso a múltiples cuentas de usuario de prueba:
 
Inicia sesión como primer usuario de prueba, navega a una página donde se carga el widget de chat e inicia una conversación. Cierra sesión y vuelve a iniciar sesión como el segundo usuario de prueba. Navega a una página donde se carga el widget de chat y comienza una conversación. Luego, ve a la bandeja de entrada en tu portal de HubSpot y verifica que los chats que llegaron eran de la primera y la segunda cuenta de prueba, respectivamente, y que ves la insignia junto a los nombres de contacto de ambos registros.
 
Nota: Para los visitantes identificados con esta API, HubSpot no eliminará la cookie messagesUtk. HubSpot también omitirá cualquier pregunta de captura de correo electrónico, ya que la dirección de correo electrónico ya se conoce. Debido a que la cookie messagesUtk y la captura de correo electrónico no se aplican a estos chats, la configuración asociada en el chatflow no se mostrará para los visitantes identificados a través de la API de identificación de visitantes.

Manual del SDK del widget de chat

Primeros pasos

 
La API está alojada en el objeto window.HubSpotConversations. Todos los métodos disponibles pueden acceder a través de este objeto. El cargador de scripts de HubSpot en tu página creará este objeto para ti, pero es posible que no esté disponible inmediatamente. Para diferir el acceso a la API hasta que esté inicializado, puedes usar la ayuda window.hsConversationsOnReady. Ve a continuación un ejemplo sencillo:
<script type="text/javascript"> function onConversationsAPIReady() { console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`); } /* configure window.hsConversationsSettings if needed. */ window.hsConversationsSettings = {}; /* If external API methods are already available, use them. */ if (window.HubSpotConversations) { onConversationsAPIReady(); } else { /* Otherwise, callbacks can be added to the hsConversationsOnReady on the window object. These callbacks will be called once the external API has been initialized. */ window.hsConversationsOnReady = [onConversationsAPIReady]; } </script>
 

Referencia de SDK

window.hsConversationsOnReady
Este es un campo especial que puedes definir en el objeto ventana que te permite especificar el código que se ejecutará tan pronto como el widget esté disponible. El uso de esta propiedad es opcional. Si se usa, este campo debe establecerse en una matriz de funciones. Una vez que la API haya sido inicializada, comprobará la existencia de esta matriz y ejecutará las funciones en serie.
if (window.HubSpotConversations) { console.log('The api is ready already'); } else { window.hsConversationsOnReady = [ () => { console.log('Now the api is ready'); }, ]; }
hsConversationsSettings
 
Este objeto te permite proporcionar algunas opciones de configuración al widget antes de inicializarlo. Para utilizar la característica de identificación de visitantes, debes establecer los siguientes campos:
Nombre de campo
Tipo de dato
Predeterminado
Descripción
loadImmediately 
 
boolean
true
Ya sea que el widget se cargue implícitamente o espere hasta que se llame al método widget.load.
identificationToken
string
“”
Se utiliza para integrarse con la API de identificación de visitantes. Este es el token proporcionado por el punto de terminación de generación de tokens en la API de identificación de visitantes que se utiliza como prueba de que este visitante ha sido identificado.
identificationEmail
string
“”
La dirección de correo electrónico del visitante que ha identificado al cargar el widget.
window.hsConversationsSettings = { loadImmediately: false, identificationEmail: "visitor-email@example.com", identificationToken: "<TOKEN FROM STEP 1>" };
Para obtener más información sobre cómo funciona el SDK del widget de chat, echa un vistazo a estos documentos.
¿Te resultó útil este artículo?
Con este formulario puedes enviar tu opinión sobre nuestros documentos para desarrolladores. Si tienes comentarios sobre el producto de HubSpot, puedes enviarlos al Foro de ideas.