Controlla Notiondesk Messenger con l'SDK JavaScript

L'SDK JavaScript di Messenger consente di integrare Messenger direttamente con l'interfaccia e lo stato della tua applicazione.

Puoi:

• Aprire e chiudere Messenger dalla propria interfaccia utente.

• Invia i visitatori direttamente a Aiuto, Messaggi, Contatti o Registro delle modifiche.

• Crea il tuo launcher di Messenger

• Reagisci agli eventi di Messenger

• Sincronizza Messenger con il tema e la lingua della tua applicazione.

• Aggiorna gli utenti autenticati senza ricaricare la pagina

• Modifica posizione e impilamento in fase di esecuzione

• Integrare Messenger con lo stato dell'applicazione React e Vue

• Rimuovere e reinizializzare Messenger quando necessario.

Utilizza l'SDK per le applicazioni che necessitano di un livello di controllo superiore a quello offerto dal frammento di installazione standard di Messenger.

Installare l'SDK

Installa il pacchetto ufficiale:

Puoi anche usare il filato:

Oppure pnpm:

Inizializza Messenger

Importa initNotiondesk() e fornisci il tuo ID Messenger:

initNotiondesk() si risolve quando Messenger è pronto per l'uso, quindi il modello più sicuro è attendere l'inizializzazione prima di chiamare i metodi SDK:

Notiondesk Messenger deve essere inizializzato nel browser. Non inizializzarlo durante il rendering lato server.

Per l'installazione di React e Next.js, consultare la guida "Come installare Notiondesk Messenger con React e Next.js" .

Apri, chiudi e attiva Messenger

Messaggero aperto

Utilizzare show():

Per esempio:

Chiudi Messenger

Utilizzare hide():

Attiva/disattiva Messenger

Utilizza toggle() per aprire Messenger quando è chiuso e chiuderlo quando è aperto:

toggle() è particolarmente utile quando la tua applicazione fornisce un proprio pulsante Messenger.

Apri una sezione specifica di Messenger

Utilizza showTab() per aprire Messenger direttamente su un modulo specifico:

Le schede disponibili sono:

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");

Per esempio:

showTab() apre anche Messenger se è attualmente chiuso.

Il modulo richiesto deve essere abilitato nella configurazione di Messenger. Ad esempio, showTab("changelog") non passerà a Changelog se il modulo Changelog è disabilitato.

Ciò consente di collegare diverse parti dell'interfaccia dell'applicazione a diverse esperienze di supporto.

Per esempio:

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

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

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

• Centro assistenza → showTab("help")

• Chiedi all'IA → showTab("messages")

• Contatta l'assistenza → showTab("contact")

• Novità → showTab("changelog")

Utilizza il tuo pulsante Messenger

Non è necessario utilizzare il launcher predefinito Notiondesk.

Disattiva la visualizzazione dell'avvio nelle impostazioni di Messenger, quindi utilizza l'SDK per aprire Messenger dalla tua interfaccia.

Per esempio:

Ciò risulta utile quando il supporto deve essere integrato in una barra di navigazione, un menu dell'account, una dashboard, un pulsante mobile o un'interfaccia applicativa già esistenti.

Quando si utilizza un launcher personalizzato, è preferibile utilizzare toggle() se lo stesso controllo deve aprire e chiudere Messenger.

Ascolta gli eventi di Messenger

L'SDK espone gli eventi tramite on() e off().

Per esempio:

on() restituisce una funzione di annullamento dell'iscrizione:

Eventi Messenger disponibili

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();

Monitora quale sezione di Messenger utilizzano i visitatori

L'evento messenger:tabChanged include la scheda corrente e quella precedente.

Ad esempio, puoi inoltrare l'attività di Messenger alla tua piattaforma di analisi:

Mantieni sincronizzato il tuo launcher

Gli eventi possono anche sincronizzare l'interfaccia utente con lo stato di Messenger:

Cambia il tema di Messenger

Utilizza setTheme() per passare dalla modalità chiara a quella scura senza ricaricare Messenger:

O:

Ad esempio, sincronizza Messenger con il tema della tua applicazione:

È inoltre possibile reagire ai cambiamenti del tema del sistema operativo:

Utilizza la dashboard Notiondesk per i colori, i caratteri, l'aspetto del launcher e altre impostazioni del marchio di Messenger. Il controllo del tema SDK è pensato per cambiare la combinazione di colori attiva.

Cambia la lingua di Messenger

Utilizzare setLanguage():

Questo è utile quando la tua applicazione dispone già di un proprio selettore di lingua:

La lingua richiesta deve essere abilitata per Messenger in Notiondesk.

Se la lingua non è abilitata, Messenger mantiene invece una lingua configurata disponibile.

Aggiorna Messenger dopo l'inizializzazione

Utilizzare updateConfig() quando lo stato dell'applicazione cambia dopo che Messenger è già stato caricato.

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

Aggiornare un utente autenticato

Dopo che un utente ha effettuato l'accesso:

Messenger aggiorna l'utente corrente senza richiedere il ricaricamento della pagina.

Torna all'utente anonimo

Quando un utente effettua il logout:

Per la procedura di autenticazione completa, vedere Identificare gli utenti connessi in Notiondesk Messenger .

Cambiare la posizione del messaggero

È possibile spostare Messenger durante l'esecuzione:

Le posizioni supportate sono:

notiondesk.updateConfig({
  userToken,
});

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

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

• bottom-right

• bottom-left

La posizione predefinita del launcher dovrebbe essere configurata normalmente nella dashboard Notiondesk. Utilizzare updateConfig() quando l'applicazione necessita di una sovrascrittura temporanea in fase di esecuzione.

Ad esempio, potresti spostare Messenger quando un altro elemento mobile occupa lo stesso angolo.

Modifica il livello di impilamento

Se Messenger deve apparire sopra un altro elemento dell'applicazione:

Utilizzare Messenger con utenti autenticati

Durante l'inizializzazione di Messenger, è necessario passare un token utente firmato:

Puoi anche iniziare in modo anonimo e identificare l'utente in un secondo momento:

Il token deve essere generato dal tuo backend.

Non esporre mai il tuo segreto dell'app Notiondesk nel codice del browser.

Per la procedura completa di autenticazione e disconnessione, consultare la sezione "Identificare gli utenti connessi in Notiondesk Messenger" .

Rimuovi Messenger

Utilizzare destroy() per rimuovere completamente l'istanza corrente di Messenger:

Utilizzare 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();

• Messenger non dovrebbe più essere presente sulla pagina corrente.

• È in corso la modifica di un account utente.

• La tua applicazione sta disinstallando l'integrazione con Messenger.

• È necessario avviare una nuova sessione di Messenger.

È possibile inizializzare nuovamente Messenger dopo averlo eliminato.

Carica Messenger senza inizializzarlo

Per le applicazioni che necessitano di un maggiore controllo sull'inizializzazione, utilizzare loadNotiondesk():

La maggior parte delle applicazioni dovrebbe utilizzare initNotiondesk() al suo posto.

loadNotiondesk() è utile quando il caricamento dell'SDK di Messenger e l'avvio di Messenger stesso devono avvenire in momenti diversi del ciclo di vita dell'applicazione.

Accedi a un'API di Messenger già caricata

Utilizza getNotiondesk() per accedere in modo sincrono all'API quando Messenger è già stato caricato:

Se Messenger non è ancora stato caricato, getNotiondesk() restituisce null.

Per l'inizializzazione normale dell'applicazione, preferire initNotiondesk().

React controlla e gestisce lo stato

Le applicazioni React dovrebbero utilizzare:

useNotiondesk() fornisce sia i controlli di Messenger sia il suo stato di caricamento corrente.

Per esempio:

I valori disponibili includono:

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>
  );
}

Utilizza api quando hai bisogno di API come le sottoscrizioni agli eventi:

Quando possibile, mantieni stabili le proprietà di configurazione come tema e lingua su NotiondeskProvider.

Per le modifiche in fase di esecuzione, è preferibile utilizzare setTheme(), setLanguage() o updateConfig() piuttosto che modificare ripetutamente la configurazione del provider.

Controlli e stato di Vue

Le applicazioni Vue possono accedere a Messenger tramite:

Per esempio:

L'integrazione con Vue espone anche l'API di Messenger, lo stato, gli errori e gli stessi controlli di runtime dell'SDK principale.

Ricette SDK comuni

Crea un pulsante di aiuto personalizzato

Disattiva il launcher predefinito nelle impostazioni di Messenger:

Apri direttamente il tuo centro assistenza

Apri direttamente il tuo assistente IA

Il modulo Messaggi deve essere abilitato e configurato in Messenger.

Apri direttamente il modulo di contatto

Apri il registro delle modifiche tramite il link "Novità".

Nascondi Messenger su un percorso specifico dell'applicazione

Sposta Messenger lontano da un altro elemento fluttuante

Monitoraggio dell'utilizzo di Messenger

Aggiorna Messenger dopo l'accesso

Cancella l'utente dopo il logout

Risoluzione dei problemi

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