Inicializar o widget do DobroDesk por código

Escolher a instalação por código quando o site tiver código de aplicação

Use o SDK por código quando o site for uma aplicação e o widget precisar iniciar depois de consentimento, autenticação, seleção de rota ou outro evento da aplicação. A incorporação por script padrão continua sendo a opção mais simples para um construtor de sites ou um campo de código personalizado aplicado ao site inteiro.

Os dois métodos carregam o mesmo widget hospedado do DobroDesk. O SDK não cria uma segunda implementação do widget. Ele fornece o ID da integração e o locale ao carregador e depois expõe métodos tipados para controlar a instância resultante.

• Use a incorporação por script quando o botão Falar com o suporte deve carregar em todas as páginas públicas sem lógica da aplicação.
• Use o SDK quando a inicialização depender do estado da aplicação ou quando um botão personalizado precisar abrir o widget.
• Inicialize o widget uma vez por página. Mantenha o cliente retornado em vez de chamar createDobroDeskWidget novamente.
• Execute a inicialização no navegador. A renderização no servidor não fornece document nem window.

Instalar o pacote

Adicione o pacote do widget do DobroDesk à aplicação frontend usando o gerenciador de pacotes que o projeto já utiliza.

npm install @dobrodesk/widget

Inicializar uma única instância do widget

1. 1

   Copie o ID da integração em Administração > Canais > Widgets do site.

   

2. 2

   Importe createDobroDeskWidget no código da aplicação executado no navegador.

3. 3

   Passe o ID da integração exato para a opção integrationId e escolha auto, en, uk, de, es, fr ou pt.

4. 4

   Armazene o cliente retornado e aguarde client.ready antes de executar uma lógica que dependa do carregamento bem-sucedido da configuração.

import { createDobroDeskWidget } from "@dobrodesk/widget";

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "auto",
});

await supportWidget.ready;

Usar o módulo ES hospedado sem um gerenciador de pacotes

Uma aplicação de navegador compatível com módulos ES pode importar o mesmo SDK diretamente. Isso é útil para um site pequeno com módulos JavaScript, mas sem uma etapa de build com npm.

import { createDobroDeskWidget } from "https://widget.dobrodesk.com/widget/sdk/v1.js";

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "en",
  openOnReady: false,
});

Controlar o widget a partir das ações da aplicação

Mantenha o cliente no módulo ou componente que controla a experiência de suporte. Quando seu próprio botão de Ajuda ou Suporte abrir o widget, inicialize-o com launcher: hidden para que o inicializador padrão não apareça ao lado dele. A lógica de consentimento pode controlar a visibilidade do inicializador depois da inicialização. O preenchimento inicial pode fornecer campos que o cliente já informou na sua aplicação.

• open, close e toggle alteram o estado do painel.
• hide remove o widget da interação, enquanto show o disponibiliza novamente.
• setLauncherVisibility oculta ou mostra somente o inicializador padrão, sem destruir o cliente do widget.
• prefill combina o nome, e-mail, assunto, mensagem ou campos personalizados configurados fornecidos.
• setLocale carrega en, uk, de, es, fr ou pt e usa o inglês para qualquer outro locale.
• destroy remove permanentemente a instância do widget da página atual.

const supportWidget = createDobroDeskWidget({
  integrationId: "wgt_7f4c1d2e3a5b6980718293a4b5c6d7e8",
  locale: "auto",
  launcher: "hidden",
});

await supportWidget.ready;

// Your application button
supportWidget.open();

// Consent or route state
supportWidget.setLauncherVisibility(false);
supportWidget.setLauncherVisibility(true);

supportWidget.close();
supportWidget.toggle();
supportWidget.hide();
supportWidget.show();

supportWidget.prefill({
  email: "customer@example.com",
  subject: "Question about order 1042",
});

supportWidget.setLocale("uk");

Identificar clientes conectados com um JWT de curta duração

Use uma identidade de cliente assinada quando sua aplicação já conhecer o cliente conectado. O DobroDesk verifica o ID do cliente e, opcionalmente, o e-mail verificado antes de vincular o histórico da conversa ou expor o contexto do CRM. O segredo da identidade deve ficar somente no gerenciador de segredos do backend.

Nas configurações do widget, escolha Exigir um usuário conectado e assinado, salve o widget e selecione Copiar segredo da identidade. Armazene esse valor como DOBRODESK_WIDGET_IDENTITY_SECRET no backend. O ID da integração público pode ficar no código do navegador. O segredo da identidade, não.

1. 1

   Instale no backend uma biblioteca JWT mantida, como jose.

2. 2

   Assine com HS256 usando o issuer dobrodesk-widget:{Integration ID}, audience igual ao ID da integração e subject igual ao ID interno estável do usuário.

3. 3

   Use uma validade de cinco minutos e nunca superior a 15 minutos. Crie um token novo quando a página carregar ou quando o usuário entrar.

4. 4

   Inclua email e email_verified: true somente depois que sua aplicação confirmar a propriedade desse endereço.

5. 5

   Retorne o token pelo endpoint autenticado do backend e passe-o para identityToken ao criar o widget.

• sub é o ID estável do usuário na sua aplicação, e não um endereço de e-mail.
• email_verified: false ou um valor omitido não torna o e-mail confiável.
• Quando o e-mail estiver em identityToken ou prefill.email, o widget não mostrará outro campo de e-mail.
• Um e-mail preenchido ou digitado sem assinatura permanece não verificado até que o cliente confirme o link de e-mail de uso único.
• Se o login ocorrer depois da inicialização, chame setIdentityToken(token) e prefill({ email, name }).
• Antes de sua aplicação desconectar o cliente, chame logout() para que outra pessoa usando o navegador não herde a conversa anterior.

import { SignJWT } from "jose";

const integrationId = process.env.DOBRODESK_WIDGET_ID;
const identitySecret = new TextEncoder().encode(
  process.env.DOBRODESK_WIDGET_IDENTITY_SECRET,
);

export const createWidgetIdentityToken = (user) =>
  new SignJWT({
    name: user.name,
    email: user.email,
    email_verified: true,
  })
    .setProtectedHeader({ alg: "HS256", typ: "JWT" })
    .setIssuer(`dobrodesk-widget:${integrationId}`)
    .setAudience(integrationId)
    .setSubject(user.id)
    .setIssuedAt()
    .setExpirationTime("5m")
    .sign(identitySecret);

// Browser code after your authenticated endpoint returns the token
const supportWidget = createDobroDeskWidget({
  integrationId,
  identityToken,
  prefill: { email: currentUser.email, name: currentUser.name },
});

Verificar a integração da aplicação

1. 1

   Carregue a rota da aplicação que inicializa o SDK e confirme que aparece somente o botão Falar com o suporte padrão ou personalizado pretendido.

   

2. 2

   Acione a ação personalizada que chama open e verifique que o painel abre sem recarregar a página.

   

3. 3

   Teste cada campo preenchido com um valor de amostra não sensível. Não coloque dados de pagamento, senhas ou tokens privados nos campos do widget.

4. 4

   Alterne entre auto, en, uk, de, es, fr e pt e confira o inicializador, os rótulos do formulário e as respostas sugeridas.

5. 5

   Envie uma mensagem de teste completa e confirme que ela chega à Caixa de entrada configurada do DobroDesk.