Come installare Notiondesk Messenger con React e Next.js

Notiondesk fornisce un SDK JavaScript ufficiale per l'installazione di Messenger nelle applicazioni React e Next.js.

Utilizza l'SDK al posto dello snippet standard di Messenger <script> quando il tuo sito web è realizzato con React, Next.js o un'altra applicazione a pagina singola.

Prima di iniziare

Ti serve:

• Un Messenger configurato nel tuo spazio di lavoro

• Il tuo ID Messenger

• Un'applicazione React o Next.js

• Accesso al codice sorgente della tua applicazione

Puoi trovare il tuo ID Messenger e le opzioni di installazione nelle impostazioni di Messenger .

Installa l'SDK di Messenger

Installa il pacchetto ufficiale:

Con il filato:

Con pnpm:

Il pacchetto ufficiale è disponibile su npm .

Installa Messenger in React

Importa NotiondeskProvider e racchiudi la parte della tua applicazione in cui Messenger dovrebbe essere disponibile.

Per la maggior parte delle applicazioni, posiziona il provider vicino alla directory principale della tua app:

Sostituisci YOUR_MESSENGER_ID con l'ID Messenger del tuo spazio di lavoro Notiondesk.

Messenger è ora disponibile per i componenti renderizzati all'interno di NotiondeskProvider.

Apri Messenger da un componente React

Utilizza l'hook useNotiondesk quando devi controllare Messenger dalla tua interfaccia.

Ad esempio, puoi creare il tuo pulsante di supporto personalizzato:

Il componente che utilizza useNotiondesk deve essere renderizzato all'interno di NotiondeskProvider.

Installa Messenger in Next.js

Messenger viene eseguito nel browser, quindi l'integrazione con Messenger deve essere inizializzata da un componente client.

L'esempio seguente utilizza il router per applicazioni Next.js.

1. Creare un componente client Notiondesk

Crea un componente come notiondesk-setup.tsx:

Sostituisci YOUR_MESSENGER_ID con il tuo ID Messenger Notiondesk.

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

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

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

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

export function App({ children }) {
  return (
    <NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
      {children}
    </NotiondeskProvider>
  );
}

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

export function SupportButton() {
  const { show } = useNotiondesk();

  return (
    <button onClick={() => void show()}>
      Contact support
    </button>
  );
}

"use client";

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

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

  return (
    <button onClick={() => void show()}>
      Contact support
    </button>
  );
}

export function NotiondeskSetup({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
      {children}
      <SupportButton />
    </NotiondeskProvider>
  );
}

2. Aggiungi il fornitore al tuo layout

Esegui il rendering del componente client dal tuo layout principale:

Inserendo NotiondeskSetup nel layout principale, Messenger diventa disponibile in tutta l'applicazione.

Se Messenger deve essere disponibile solo in specifiche sezioni della tua applicazione, inserisci il provider in un layout o in una pagina più specifici.

Controllare Messenger a livello programmatico

L'hook di React espone i controlli di Messenger che puoi utilizzare dai tuoi componenti.

Per esempio:

È possibile utilizzare questi metodi per collegare Messenger ai propri pulsanti, alla navigazione, ai menu di supporto o ad altri elementi dell'interfaccia utente dell'applicazione.

L'SDK supporta anche configurazioni e controlli aggiuntivi, come la modifica della lingua o del tema.

Carica Messenger in modo condizionale

È possibile impedire il caricamento di Messenger agli utenti che non dovrebbero avervi accesso tramite l'opzione enabled:

La logica di gestione dei permessi della tua applicazione deve decidere se abilitare o meno Messenger.

Questa opzione è utile quando Messenger deve essere disponibile solo per i clienti che hanno effettuato l'accesso, per specifici piani tariffari o per determinate aree dell'applicazione.

import { NotiondeskSetup } from "./notiondesk-setup";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <NotiondeskSetup>
          {children}
        </NotiondeskSetup>
      </body>
    </html>
  );
}

const notiondesk = useNotiondesk();

await notiondesk.show();
await notiondesk.hide();
await notiondesk.toggle();

<NotiondeskProvider
  messengerId="YOUR_MESSENGER_ID"
  enabled={currentUser.canUseSupportWidget}
>
  {children}
</NotiondeskProvider>

Identificare gli utenti che hanno effettuato l'accesso

Notiondesk Messenger può identificare gli utenti autenticati utilizzando un token utente firmato generato dal tuo backend.

Trasmetti il ​​token al fornitore:

Non esporre mai il tuo segreto dell'app Notiondesk nel codice React o in altri codici del browser.

Il segreto dell'app deve rimanere sul tuo server. Il tuo frontend deve ricevere solo il token utente firmato e di breve durata generato dal tuo backend.

Verificare l'installazione

Dopo aver installato l'SDK:

<NotiondeskProvider
  messengerId="YOUR_MESSENGER_ID"
  userToken={userToken}
>
  {children}
</NotiondeskProvider>

1. Avvia o distribuisci la tua applicazione.

2. Apri una pagina visualizzata all'interno di NotiondeskProvider

3. Verifica che Messenger si carichi correttamente

4. Se hai aggiunto un pulsante di supporto personalizzato, fai clic su di esso e conferma che Messenger si apre

5. Verifica la navigazione tra le pagine della tua applicazione

6. Controlla la console del browser per eventuali errori JavaScript.

Per Next.js, è consigliabile testare anche una build di produzione, poiché il comportamento di rendering client/server può differire da quello in ambiente di sviluppo locale.

Risoluzione dei problemi

"use client";

<NotiondeskProvider messengerId="YOUR_MESSENGER_ID">
  <SupportButton />
</NotiondeskProvider>

const { show } = useNotiondesk();

<button onClick={() => void show()}>
  Contact support
</button>