Integrar o SDK do widget web DobroDesk

Instalar o pacote publicado

O pacote de navegador está publicado em https://www.npmjs.com/package/@dobrodesk/widget/v/0.3.1. Fixe a versão no lockfile e copie o Integration ID público em Admin > Channels > Website widgets.

npm install @dobrodesk/widget@0.3.1

Configurar e apresentar o widget

Depois da instalação, copie o Integration ID público de Admin > Channels > Website widgets e configure o widget na sua aplicação.

Use launcher: hidden quando a sua aplicação for proprietária do botão. O launcher integrado oculta-se enquanto o painel está aberto e devolve o foco ao fechar. Omita um override de reduceMotion para o widget seguir a preferência atual do sistema, incluindo alterações a prefers-reduced-motion durante a sessão.

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

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

await widget.ready;
widget.open();

Usar um acionador personalizado ou uma superfície integrada

Use launcher: hidden quando o seu aplicativo controla o acionador. Para uma superfície integrada, defina largura e altura estáveis antes da montagem para evitar mudanças no layout durante o carregamento.

O botão personalizado deve ser acessível pelo teclado e expor aria-controls e aria-expanded. Ao montar novamente, reutilize o mesmo cliente, a mesma sessão e o mesmo rascunho.

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

const supportSlot = document.querySelector("#support-slot");
const helpButton = document.querySelector("#help-button");
if (!(supportSlot instanceof HTMLElement) || !(helpButton instanceof HTMLButtonElement)) {
  throw new Error("Support widget host elements are missing");
}

const widget = createDobroDeskWidget({
  integrationId: "wgt_0123456789abcdef0123456789abcdef",
  launcher: "hidden",
  container: supportSlot,
});

helpButton.addEventListener("click", () => widget.toggle());
widget.onStateChange((state) => {
  helpButton.setAttribute("aria-expanded", String(state.visible));
});
await widget.ready;

Tratar carregamento e identidade assinada

O frame do widget controla os indicadores de carregamento visíveis pelo cliente. Use onLoadingChange para o estado da página, por exemplo para desativar uma ação de checkout envolvente. As fases incluem inicialização, carregamento de conteúdo e sessão, entrega de mensagem, espera do assistente, execução de ação e reconexão.

As sessões web anónimas são suportadas. Para um cliente assinado, o seu backend deve emitir um JWT de identidade HS256 de curta duração e o navegador pode enviá-lo com o email conhecido. Nunca coloque o signing secret ou um support API token no código do navegador. Chame logout antes de terminar a sessão autenticada do host ou de outro cliente usar o navegador.

const stopLoading = widget.onLoadingChange((loading) => {
  checkoutButton.disabled = loading.active;
});

// The token is returned by your backend. This function belongs to your app.
widget.setIdentityToken(await loadIdentityTokenFromYourBackend());
widget.prefill({ email: currentUser.email, name: currentUser.name });

Tratar carregamento, visibilidade e acessibilidade

Use hooks de carregamento ou eventos tipados para o estado da tela hospedeira. A superfície mostra o carregamento das mensagens, a espera e as tentativas novamente para evitar um segundo indicador sobre o campo de entrada.

Oculte ou mostre a superfície durante uma navegação temporária mantendo o cliente. O widget respeita as preferências do sistema para reduzir movimento. Remover ou fechar a vista não descarta a sessão nem o rascunho.

1. Ao montar novamente, reutilize o mesmo cliente e dimensões estáveis do contêiner.
2. Use a função de visibilidade para ocultar temporariamente, sem redefinir a sessão.
3. Finalize a sessão apenas ao sair ou trocar de conta de forma intencional.

Verificar a integração

1. Abra a página a partir de um origin permitido e confirme que o painel abre uma vez e que o launcher oculto permanece oculto.
2. Envie uma mensagem de teste de uma sessão privada do navegador e confirme que chega à Inbox configurada sem criar outra conversa.
3. Desative brevemente a rede e aguarde o estado de reconexão do widget. Deixe o frame repetir a operação pendente. Não envie a mesma mensagem por outro controlo enquanto o primeiro pedido estiver sem resultado.
4. Altere a definição do sistema para reduzir movimento com o widget aberto e confirme que as transições seguintes respeitam a nova preferência.