Controle o Messenger Notiondesk com o SDK JavaScript.

O SDK JavaScript do Messenger permite que você integre o Messenger diretamente com a interface e o estado do seu aplicativo.

Você pode:

• Abra e feche o Messenger a partir da sua própria interface de usuário.

• Direcione os visitantes diretamente para Ajuda, Mensagens, Contato ou Registro de alterações.

• Crie seu próprio iniciador do Messenger

• Reaja aos eventos do Messenger

• Sincronize o Messenger com o tema e o idioma do seu aplicativo.

• Atualize os usuários autenticados sem recarregar a página.

• Alterar posição e empilhamento em tempo de execução

• Integre o Messenger com o estado de aplicativos React e Vue.

• Remova e reinicialize o Messenger quando necessário.

Use o SDK para aplicativos que precisam de mais controle do que o trecho de instalação padrão do Messenger oferece.

Instale o SDK

Instale o pacote oficial:

Você também pode usar o Yarn:

Ou pnpm:

Inicializar o Messenger

Importe initNotiondesk() e forneça seu ID do Messenger:

initNotiondesk() é resolvido quando o Messenger está pronto para uso, portanto, o padrão mais seguro é aguardar a inicialização antes de chamar os métodos do SDK:

Notiondesk O Messenger precisa ser inicializado no navegador. Não o inicialize durante a renderização no servidor.

Para instalação do React e Next.js, consulte Como instalar o Notiondesk Messenger com React e Next.js.

Abrir, fechar e ativar/desativar o Messenger

Abra o Messenger

Usar show():

Por exemplo:

Fechar Messenger

Usar hide():

Alternar Messenger

Use toggle() para abrir o Messenger quando ele estiver fechado e fechá-lo quando estiver aberto:

toggle() é particularmente útil quando seu aplicativo fornece seu próprio botão do Messenger.

Abra uma seção específica do Messenger

Use showTab() para abrir o Messenger diretamente em um módulo específico:

As abas disponíveis são:

npm install @notiondesk-so/messenger-js-sdk

yarn add @notiondesk-so/messenger-js-sdk

pnpm add @notiondesk-so/messenger-js-sdk

import { initNotiondesk } from "@notiondesk-so/messenger-js-sdk";

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

await notiondesk.show();

await notiondesk.show();

document.querySelector("#support")?.addEventListener("click", () => {
  void notiondesk.show();
});

await notiondesk.hide();

await notiondesk.toggle();

notiondesk.showTab("help");

Por exemplo:

showTab() também abre o Messenger se ele estiver fechado no momento.

O módulo solicitado deve estar habilitado na sua configuração do Messenger. Por exemplo, showTab("changelog") não mudará para Changelog se o módulo Changelog estiver desabilitado.

Isso possibilita conectar diferentes partes da interface do seu aplicativo a diferentes experiências de suporte.

Por exemplo:

helpButton.addEventListener("click", () => {
  notiondesk.showTab("help");
});

updatesButton.addEventListener("click", () => {
  notiondesk.showTab("changelog");
});

contactButton.addEventListener("click", () => {
  notiondesk.showTab("contact");
});

• Central de Ajuda → showTab("help")

• Pergunte à IA → showTab("messages")

• Contate o suporte → showTab("contact")

• Novidades → showTab("changelog")

Use seu próprio botão do Messenger

Você não precisa usar o iniciador padrão Notiondesk.

Desative a opção "Mostrar inicializador" nas configurações do Messenger e, em seguida, use o SDK para abrir o Messenger a partir da sua interface.

Por exemplo:

Isso é útil quando o suporte precisa ser integrado a uma barra de navegação existente, menu de conta, painel de controle, botão flutuante ou estrutura de aplicativo.

Ao usar um iniciador personalizado, prefira toggle() se o mesmo controle deve abrir e fechar o Messenger.

Ouça os eventos do Messenger

O SDK expõe eventos através de on() e off().

Por exemplo:

on() retorna uma função de cancelamento de inscrição:

Eventos disponíveis no Messenger

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

document.querySelector("#help")?.addEventListener("click", () => {
  void notiondesk.toggle();
});

notiondesk.on("messenger:show", () => {
  console.log("Messenger opened");
});

notiondesk.on("messenger:hide", () => {
  console.log("Messenger closed");
});

const unsubscribe = notiondesk.on("messenger:show", () => {
  console.log("Messenger opened");
});

// Later
unsubscribe();

Acompanhe qual seção do Messenger os visitantes usam.

O evento messenger:tabChanged inclui a aba atual e a anterior.

Por exemplo, você pode encaminhar a atividade do Messenger para sua plataforma de análise:

Mantenha seu próprio iniciador sincronizado

Os eventos também podem sincronizar sua interface de usuário com o estado do Messenger:

Alterar o tema do Messenger

Use setTheme() para alternar entre o modo claro e o modo escuro sem recarregar o Messenger:

Ou:

Por exemplo, sincronize o Messenger com o tema do seu aplicativo:

Você também pode reagir a alterações no tema do sistema operacional:

Use o painel de controle Notiondesk para configurar as cores, fontes, aparência do iniciador e outras preferências da sua marca no Messenger. O controle de tema do SDK serve para alternar o esquema de cores ativo.

Alterar o idioma do Messenger

Usar setLanguage():

Isso é útil quando seu aplicativo já possui seu próprio seletor de idioma:

O idioma solicitado deve estar habilitado para o seu Messenger em Notiondesk.

Se a localidade não estiver ativada, o Messenger manterá um idioma configurado disponível.

Atualizar o Messenger após a inicialização

Use updateConfig() quando o estado do aplicativo mudar depois que o Messenger já tiver sido carregado.

notiondesk.on(
  "messenger:tabChanged",
  ({ tabName, previousTab }) => {
    console.log("Messenger tab:", tabName);
  },
);

notiondesk.on("messenger:show", () => {
  analytics.track("support_opened");
});

notiondesk.on("messenger:tabChanged", ({ tabName }) => {
  analytics.track("support_tab_opened", {
    tab: tabName,
  });
});

notiondesk.on("messenger:show", () => {
  helpButton.setAttribute("aria-expanded", "true");
});

notiondesk.on("messenger:hide", () => {
  helpButton.setAttribute("aria-expanded", "false");
});

notiondesk.setTheme("dark");

notiondesk.setTheme("light");

notiondesk.setTheme(
  isDarkMode ? "dark" : "light",
);

const colorScheme = window.matchMedia(
  "(prefers-color-scheme: dark)",
);

function syncMessengerTheme() {
  notiondesk.setTheme(
    colorScheme.matches ? "dark" : "light",
  );
}

syncMessengerTheme();

colorScheme.addEventListener(
  "change",
  syncMessengerTheme,
);

notiondesk.setLanguage("fr");

notiondesk.setLanguage(currentLocale);

Atualizar um usuário autenticado

Após o usuário efetuar o login:

O Messenger atualiza o usuário atual sem exigir que a página seja recarregada.

Voltar ao usuário anônimo

Quando um usuário faz logout:

Para o fluxo de autenticação completo, consulte Identificar usuários conectados no Messenger .

Alterar a posição do mensageiro

Você pode mover o Messenger em tempo de execução:

As posições com suporte são:

notiondesk.updateConfig({
  userToken,
});

notiondesk.updateConfig({
  userToken: null,
});

notiondesk.updateConfig({
  position: "bottom-left",
});

• bottom-right

• bottom-left

A posição padrão do iniciador deve ser configurada no painel Notiondesk. Use updateConfig() quando seu aplicativo precisar de uma substituição temporária em tempo de execução.

Por exemplo, você pode mover o Messenger quando outro elemento flutuante ocupar o mesmo canto.

Alterar o nível de empilhamento

Caso o Messenger precise aparecer acima de outro elemento do aplicativo:

Use o Messenger com usuários autenticados.

Forneça um token de usuário assinado ao inicializar o Messenger:

Você também pode começar anonimamente e identificar o usuário posteriormente:

O token deve ser gerado pelo seu backend.

Nunca exponha o segredo do seu aplicativo Notiondesk no código do navegador.

Consulte Identificar usuários conectados no Messenger para obter o fluxo completo de autenticação e logout.

Remover Messenger

Use destroy() para remover completamente a instância atual do Messenger:

Use destroy() quando:

notiondesk.updateConfig({
  zIndex: 10000,
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
  userToken,
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

notiondesk.updateConfig({
  userToken,
});

notiondesk.destroy();

• O Messenger não deve mais estar presente na página atual.

• Uma conta de usuário está sendo alterada.

• Seu aplicativo está desmontando a integração com o Messenger.

• Você precisa iniciar uma nova sessão do Messenger.

Você pode inicializar o Messenger novamente após destruí-lo.

Carregar o Messenger sem inicializá-lo

Para aplicações que necessitam de maior controle sobre a inicialização, utilize loadNotiondesk():

A maioria das aplicações deve usar initNotiondesk() em vez disso.

loadNotiondesk() é útil quando o carregamento do SDK do Messenger e a inicialização do próprio Messenger precisam ocorrer em pontos diferentes do ciclo de vida do seu aplicativo.

Acesse uma API do Messenger já carregada.

Use getNotiondesk() para acessar a API de forma síncrona quando o Messenger já estiver carregado:

Se o Messenger ainda não tiver carregado, getNotiondesk() retorna null.

Para inicialização normal do aplicativo, prefira initNotiondesk().

Controles e estado do React

Aplicações React devem usar:

useNotiondesk() fornece os controles do Messenger e seu estado de carregamento atual.

Por exemplo:

Os valores disponíveis incluem:

import {
  loadNotiondesk,
} from "@notiondesk-so/messenger-js-sdk";

const notiondesk = await loadNotiondesk();

await notiondesk.init({
  messengerId: "YOUR_MESSENGER_ID",
});

import {
  getNotiondesk,
} from "@notiondesk-so/messenger-js-sdk";

getNotiondesk()?.show();

import {
  NotiondeskProvider,
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/react";

function SupportButton() {
  const {
    show,
    status,
  } = useNotiondesk();

  return (
    <button
      disabled={status !== "ready"}
      onClick={() => void show()}
    >
      Contact support
    </button>
  );
}

Use api quando precisar de APIs como assinaturas de eventos:

Mantenha as propriedades de configuração, como tema e idioma, estáveis ​​em NotiondeskProvider sempre que possível.

Para alterações em tempo de execução, prefira setTheme(), setLanguage() ou updateConfig() em vez de alterar repetidamente a configuração do provedor.

Controles e estado do Vue

Os aplicativos Vue podem acessar o Messenger usando:

Por exemplo:

A integração com o Vue também expõe a API do Messenger, o status, os erros e os mesmos controles de tempo de execução do SDK principal.

Receitas comuns do SDK

Crie um botão de Ajuda personalizado

Desative o iniciador padrão nas configurações do seu Messenger:

Abra sua central de ajuda diretamente

Abra seu assistente de IA diretamente

O módulo Mensagens deve estar ativado e configurado no Messenger.

Abra seu formulário de contato diretamente

Abra o registro de alterações a partir do link "Novidades".

Ocultar o Messenger em uma rota de aplicativo específica

Mova o Messenger para longe de outro elemento flutuante.

Monitorar o uso do Messenger

Atualize o Messenger após o login.

Limpar o usuário após o logout

Solução de problemas

import { useEffect } from "react";
import { useNotiondesk } from "@notiondesk-so/messenger-js-sdk/react";

function MessengerAnalytics() {
  const { api } = useNotiondesk();

  useEffect(() => {
    if (!api) {
      return;
    }

    return api.on("messenger:show", () => {
      analytics.track("support_opened");
    });
  }, [api]);

  return null;
}

import {
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/vue";

<script setup lang="ts">
import {
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/vue";

const {
  show,
  showTab,
  isReady,
} = useNotiondesk();
</script>

<template>
  <button
    :disabled="!isReady"
    @click="show()"
  >
    Contact support
  </button>

  <button @click="showTab('changelog')">
    What's new
  </button>
</template>

helpButton.addEventListener("click", () => {
  void notiondesk.toggle();
});

notiondesk.showTab("help");

notiondesk.showTab("messages");

notiondesk.showTab("contact");

notiondesk.showTab("changelog");

if (window.location.pathname.startsWith("/checkout")) {
  await notiondesk.hide();
}

notiondesk.updateConfig({
  position: "bottom-left",
});

notiondesk.on("messenger:show", () => {
  analytics.track("support_opened");
});

notiondesk.on("messenger:tabChanged", ({ tabName }) => {
  analytics.track("support_section_opened", {
    section: tabName,
  });
});

notiondesk.updateConfig({
  userToken,
});

notiondesk.updateConfig({
  userToken: null,
});

try {
  const notiondesk = await initNotiondesk({
    messengerId: "YOUR_MESSENGER_ID",
  });
} catch (error) {
  console.error(
    "Could not initialize Notiondesk Messenger",
    error,
  );
}

notiondesk.updateConfig({
  zIndex: 10000,
});

notiondesk.updateConfig({
  userToken: null,
});

notiondesk.destroy();

const { show, status } = useNotiondesk();

return (
  <button
    disabled={status !== "ready"}
    onClick={() => void show()}
  >
    Contact support
  </button>
);