Ativação de visitantes autenticados no widget do Chat

Com a nova API do JavaScript e token JWT, você pode configurar seu widget para autenticar os visitantes em todas as páginas carregadas.

Este artigo se aplica a clientes que usam as seguintes versões do Chat:

• Zendesk Chat na fase 3 (apenas Chat)

Se você está usando alguma das versões a seguir, consulte Ativação de visitantes autenticados no Web Widget (clássico):

• Zendesk Chat na fase 4 (apenas Chat ou com Support)
• Zendesk Chat na fase 3 (com o chat em tempo real no Web Widget (clássico))

Para identificar a versão do Chat que você está usando, consulte Determinação da versão de sua conta do Zendesk Chat.

Este artigo inclui os tópicos a seguir:

• Visão geral
• Geração de um novo segredo compartilhado do Chat
• Criação do token JWT
• Amostras de código
• Sobre a experiência do agente com visitantes autenticados
• Sobre a experiência do widget com visitantes autenticados

Visão geral

Ao configurar o widget de Chat para usar visitantes autenticados, você aproveita os seguintes benefícios:

• Maior confiança e segurança para seus visitantes/clientes e agentes de que a pessoa do outro lado da conversa é real.

• Suporte para tráfego por diferentes domínios. Se você estiver inserindo o widget em vários domínios ou vinculando a serviços com hospedagem externa (por exemplo, o Shopify), autenticar o visitante trará as informações desses diferentes domínios até a plataforma do Chat, dando mais contexto aos agentes.

• Suporte para identificação por diferentes dispositivos/navegadores. Quando a ID personalizada é especificada na chamada de autenticação, o visitante pode ser reconhecido como sendo a mesma pessoa mesmo se ele mudar de dispositivo ou navegador.

Geração de um novo segredo compartilhado do Chat

Para configurar seu widget para autenticar visitantes, você precisa de um segredo compartilhado. Como o segredo compartilhado é uma configuração de segurança, ele deve ser gerado, copiado e colado em uma mensagem informativa para sua equipe de engenheiros, ou diretamente em sua base de códigos apenas uma vez. Ele não deve ser inserido no navegador.

Apenas os administradores do Chat podem definir configurações de autenticação do visitante.

Como gerar o segredo compartilhado necessário para os visitantes autenticados

1. Abra o painel do Chat e visite Configurações > Widget.
2. Clique na aba Segurança do widget.
3. Role até a seção Autenticação do visitante e clique no botão Gerar.

Observação: o segredo compartilhado deve permanecer seguro, por isso, ele será exibido por completo apenas uma vez. Se você não tem acesso ao segredo compartilhado e precisa do segredo completo para criar seu token, pode redefini-lo clicando em “Gerar novamente”.

Gerar um novo segredo compartilhado revogará o token antigo. Se você acha que seu segredo compartilhado não é mais seguro, gere um novo. Se você precisar alterar o segredo sempre, deve programar a geração para quando o Chat estiver offline, pois isso desconecta os visitantes do widget por 5 minutos.

Após gerar o segredo compartilhado, use-o para criar um token JWT (aprenda mais sobre JWT), que você adicionará ao seu trecho do Web Widget.

Criação do token JWT

Como criar um token JWT e adicionar o código ao trecho do Chat independente

1. Crie uma carga de dados do lado do servidor para o token de JWT. As seguintes informações são necessárias:
   • name: nome do cliente
   • email: e-mail do cliente
   • external_id: cadeia de caracteres alfanumérica; é um identificador exclusivo do cliente. Após o valor ser definido para o cliente, ele não pode ser alterado. Recomendamos que você use a ID de usuário exclusiva do seu sistema nesse campo. Por exemplo, user-123456.
   • iat: valor inteiro do carimbo de data e hora atual, em segundos. Algumas funções em linguagens específicas como, por exemplo, Date.now() do JavaScript, retorna milissegundos, portanto, não esqueça de converter para segundos. A autenticação Iat para o Chat permite até dois minutos de distorção do relógio.
   • exp: valor inteiro do carimbo de data e hora atual, em segundos. Esse valor indica a validade desse token JWT. O valor máximo permitido é de até 7 minutos do valor de iat.
2. Especifique HS256 como o algoritmo JWT no cabeçalho da sua carga de JWT:

   {
     "typ":"JWT",
     "alg":"HS256"
   }

   HS256 quer dizer HMAC SHA 256, um algoritmo de criptografia de 256 bits criado pela Agência de Segurança Nacional dos Estados Unidos.

   Observação: o Zendesk não oferece suporte aos algoritmos JWT RS256 e ES256.
3. Use as amostras de código abaixo para encontrar um modelo que atenda às suas necessidades de linguagem.
4. Use a API do JavaScript $zopim.livechat.authenticate para fornecer uma função que gera um novo JWT sempre que é invocada. Segue um exemplo de código:

   $zopim(function() {
     $zopim.livechat.authenticate({
       jwtFn: function(callback) {
         fetch('JWT_TOKEN_ENDPOINT').then(function(res) {
           res.text().then(function(jwt) {
             callback(jwt);
           });
         });
       }
     });
   });

   No exemplo acima, JWT_TOKEN_ENDPOINT é o ponto de extremidade que pode ser implementado no seu servidor para obter um novo JWT.

   Observação: o jwtFn pode ser chamado várias vezes ao longo de uma sessão de chat para obter um novo JWT e validar a identidade do visitante pela sessão.
5. Você pode usar a API $zopim.livechat.clearAll() para desconectar o usuário do widget quando ele desconectar do aplicativo/website hospedeiro.

   Para aplicativos de página única, observe que não é possível autenticar um visitante novamente após usar a API $zopim.livechat.clearAll(). Você precisa recarregar a página para autenticar o visitante novamente.

Amostras de código

Seu token precisa ser gerado dinamicamente do lado do servidor no carregamento da página. Encontre o modelo abaixo que atenda às suas necessidades de linguagem. Personalize a amostra como desejar, certificando-se de substituir #{details} com suas próprias informações.

Se nenhuma dessas amostras atender às suas necessidades, o JWT tem uma lista mais extensa de bibliotecas de JWT para explorar.

• Ruby
• NodeJS
• Python
• PHP
• Elixir

Ruby

Primeiramente, instale ruby-jwt.

Se você estiver usando Rubygems:

gem install jwt

Se estiver usando o Bundler, adicione o seguinte ao seu arquivo gem:

gem 'jwt'

Depois, gere um token usando o segredo compartilhado:

require 'jwt'
payload = {
  :name => "#{customerName}",
  :email => "#{customerEmail}",
  :iat => timestamp,
  :external_id => "#{externalId}"
}
token = JWT.encode payload, "#{yourSecret}"

NodeJS

Instale jsonwebtoken:

npm install jsonwebtoken --save-dev

Depois, gere um token usando o segredo compartilhado:

var jwt = require('jsonwebtoken'); 
var payload = {
  name: '#{customerName}',
  email: '#{customerEmail}',
  iat: #{timestamp},
  external_id: '#{externalId}'
};
var token = jwt.sign(payload, '#{yourSecret}');

Python

Instale python-jose:

pip install python-jose

Gere um token usando o segredo compartilhado:

from jose import jwt
var payload = {
  'name': '#{customerName}',
  'email': '#{customerEmail}',
  'iat': #{timestamp}, 
  'external_id': '#{externalId}'
}
token = jwt.encode(payload, '#{yourSecret}'

PHP

Baixe PHP-JWT:

composer require firebase/php-jwt

Gere um token usando o segredo compartilhado:

use \Firebase\JWT\JWT;
$payload = {
  'name' => '#{customerName}' ,
  'email' => '#{customerEmail}',
  'iat' => #{timestamp},
  'external_id' => '#{externalId}'
};
$token = JWT::encode($payload, '#{yourSecret}');

Elixir

Adicione ‘json_web_token_ex’ ao seu arquivo ‘mix.exs’:

defp deps do
  [{:json_web_token, "~> 0.2"}]
end

Gere um token usando o segredo compartilhado:

data = %{
  name: "#{customerName}",
  email: "#{customerEmail}",
  iat: "#{timestamp}",
  external_id: "#{externalId}"
}
options = %{ key: "#{yourSecret}" }
jwt = JsonWebToken.sign data, options

Sobre a experiência do agente com visitantes autenticados

Há algumas atualizações no painel do Chat quando um agente começa a conversar por chat com um visitante autenticado.

Primeiro, o agente reconhece que o visitante é autenticado pela marca de verificação verde que sobrepõe o avatar do visitante:

O agente também poderá notar que não pode editar o nome e o e-mail do visitante, pois essas informações verdadeiras são enviadas pela API do JavaScript.

Por último, banir um visitante autenticado significa que ele não poderá acessar o widget de Chat por dispositivos e navegadores.

Sobre a experiência do widget com visitantes autenticados

A experiência dos visitantes autenticados no widget do Chat é um pouco diferente. Primeiro: sua informação é somente-leitura e não pode ser modificada usando o widget ou as APIs do JavaScript.

Segundo: as sessões de chat em andamento são sincronizadas pelos dispositivos quando o visitante está autenticado. Isso dá ao visitante a flexibilidade de trocar de computador/navegador e continuar sua sessão de chat em andamento se, por exemplo, ele estiver alternando entre os widgets do Chat em um navegador da web para desktop e um navegador da web para dispositivos móveis.

Observação: como os SDKs para dispositivos móveis atuais do Chat não oferecem suporte à autenticação do visitante, os visitantes não podem continuar uma sessão de chat ao alternar entre o widget para desktop e um aplicativo para dispositivos móveis usando o SDK do Chat.

Por último, não há recurso de chat em janela pop-out para os visitantes autenticados porque não é possível verificar a identidade por esse tipo de janela (visto que a experiência está hospedada em nosso domínio zopim.com).