Identificação do visitante

Visão geralEndpoint
APPLICABLE PRODUCTS
  • Marketing Hub
    • Professional or Enterprise
  • Sales Hub
    • Professional or Enterprise
  • Service Hub
    • Professional or Enterprise
  • Content Hub
    • Professional or Enterprise
Use the Visitor Identification API to identify visitors to your site that were authenticated using your own external authentication system.
 
An identification token returned from this API can be used to pass information about your already-authenticated visitor to the chat widget, so that it treats the visitor as a known contact. Agents in the inbox can then have confidence about who they are talking to, and visitors can access previous thread history across devices. For example:

Please note:

  • The Visitor Identification API is for telling HubSpot who the visitor is. You should not rely on this to authenticate users in your platform.
  • Access to the Visitor Identification API requires a Professional or Enterprise level subscription. If the account does not have a qualifying subscription, you will receive a 403 error response from the API.

Exemplo de fluxo de integração

Para se integrar a esse recurso, você deve ter um aplicativo da Web existente com um sistema de autenticação. 

Antes de começar, certifique-se de ter um app privado configurado e de que a conta que está tentando integrar tem uma assinatura Professional ou Enterprise.
 
Veja um exemplo de um possível fluxo de integração:
Possível fluxo de identificação do usuário
Depois que o seu cliente estiver conectado e verificado em seu sistema, siga as seguintes etapas para identificá-lo no chat em tempo real:

1. No front-end, defina loadImmediately como false no objeto hsConversationsSettings na janela. Se você não fizer isso, o widget de chat pode ser carregado antes que as informações de identificação sejam passadas. Veja as informações do SDK do widget de chat abaixo para obter mais informações.

  • Defina as propriedades hsConversationsSettings fora da função isConversationsAPIReady.
  • O hsConversationsSettings precisa ser definido antes da chamada, caso contrário, você poderá enfrentar uma condição de corrida que interfere no carregamento do widget.
window.hsConversationsSettings = { loadImmediately: false };

2. Gere um token por meio da API de identificação do visitante, passando o endereço de e-mail do visitante autenticado. Isso deve ser feito na parte de trás do seu aplicativo da Web. Consulte a guia Endpoints para ver um exemplo de solicitação.

curl --request POST \ --url 'https://api.hubspot.com/conversations/v3/visitor-identification/tokens/create \ --data '{ "email": "gob@bluth.com", "firstName": "Gob", "lastName": "Bluth" }'
The provided first and last name will be set on the contact record in HubSpot after the chat begins if:
  • it's a new contact created by the Visitor Identification API.
  • it's an existing contact where the name is not already known.

This can be useful when personalizing messages to identified visitors when your external system already has name information, but it does not yet exist in HubSpot. These are optional parameters and not required. 

3. Usando a Etapa 2 do token, defina as seguintes propriedades no objeto hsConversationsSettings na janela.

window.hsConversationsSettings = { identificationEmail: "visitor-email@example.com", identificationToken: "<TOKEN FROM STEP 1>" };

4. Carregue o widget.

window.HubSpotConversations.widget.load();

O token e o e-mail devem ser definidos no objeto hsConversationsSettings na janela sempre que a página for carregada para um visitante autenticado. Este contexto não será transferido por meio de carregamentos de página automaticamente se esses parâmetros não estiverem mais definidos. Os tokens são temporários e expirarão após 12 horas. Os tokens podem ser armazenados em cache para evitar a recuperação do token em cada carregamento de página, desde que sejam atualizados, no mínimo, a cada 12 horas. 

Verificar a integração

Depois de concluir a integração do recurso de Identificação do visitante, você pode verificar se está funcionando conforme o esperado. Há várias maneiras de fazer isso, dependendo da sua implementação; portanto, você pode precisar adaptar os exemplos abaixo aos seus requisitos específicos.

  • Se você tiver adicionado o widget de chat a uma ou mais páginas públicas, bem como por trás de um sistema de autenticação:
    • Acesse uma página em que o widget de chat não deve identificar visitantes e inicie uma conversa.
    • No HubSpot, abra a caixa de entrada e verifique se o chat que acabou de chegar pertence a um Visitante desconhecido. Se esse não for o caso, tente seguir estas etapas em uma janela de navegação privada:
      • Acesse uma página em que o widget de chat deve identificar visitantes por meio da API de identificação de visitante e inicie uma conversa.
      • No HubSpot, abra a caixa de entrada e verifique se o chat foi atribuído corretamente ao contato em que você está conectado. Você deve ver um emblema ao lado do nome do contato. Isso indica que esse contato foi identificado com sucesso por meio dessa API.

        visitor_identity_badge
  • Se você apenas tiver adicionado o widget de chat a páginas por trás de um sistema de autenticação e tiver acesso a várias contas de usuário de teste:
    • Faça login no HubSpot como o primeiro usuário de teste, acesse uma página em que o widget de chat é carregado e inicie uma conversa.
    • Desconecte-se e faça login novamente como o segundo usuário de teste. Navegue até uma página em que o widget de bate-papo é carregado e inicie uma conversa.
    • No HubSpot, abra a caixa de entrada e verifique se os chats recebidos são da primeira e da segunda contas de teste, respectivamente, e se você vê o emblema ao lado dos nomes de contato de ambos os registros.

Please note: for visitors identified with this API, HubSpot will not drop the messagesUtk cookie. HubSpot will also skip any email capture questions since email address is already known. Because the messagesUtk cookie and email capture do not apply to these chats, the associated settings in the chatflow will not show for visitors identified through the Visitor Identification API.

Informações do SDK de widget de chat

A API está hospedada no objeto window.HubSpotConversations. Todos os métodos disponíveis podem ser acessados por meio desse objeto. O carregador de script do HubSpot na sua página criará esse objeto para você, mas pode não estar disponível imediatamente. Para adiar o acesso à API até que ela seja inicializada, você pode usar o assistente window.hsConversationsOnReady. Por exemplo:

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

SDK reference

window.hsConversationsOnReady array

This is an optional field you can define on the window object that enables you to specify code to be executed as soon as the widget becomes available. Once the API has been initialized, it will check for the existence of this array and execute its functions in series.

if (window.HubSpotConversations) { console.log('The api is ready already'); } else { window.hsConversationsOnReady = [ () => { console.log('Now the api is ready'); }, ]; }

Objeto hsConversationsSettings

Esse objeto permite oferecer algumas opções de configuração para o widget antes que ele inicie. Para usar o recurso Identificação de visitante, você deve definir os seguintes campos:

Use this table to describe parameters / fields
ParameterTypeDescription Default
loadImmediately
boolean

Se o widget deve ser carregado implicitamente ou aguardar até que o método widget.load seja chamado

 true
identificationToken
string

Usado para integrar com a API de identificação de visitante. Este é o token fornecido pelo endpoint de geração de token na API de identificação de visitante usada como prova de que esse visitante foi identificado.

 ""
identificationEmail
string

O endereço de e-mail do visitante identificado como aquele que carregou o widget.

 ""
window.hsConversationsSettings = { loadImmediately: false, identificationEmail: "visitor-email@example.com", identificationToken: "<TOKEN FROM STEP 1>" };

Saiba mais sobre o SDK de conversas.

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..