Comment intégrer le widget en libre-service

Le widget en libre-service s’intègre à votre site web à l’aide d’un simple extrait de script.

Une fois ajouté à votre HTML, il apparaît sous forme de bouton flottant sur toutes les pages où le script est chargé, permettant aux visiteurs d’accéder instantanément à votre centre d’aide.

Prérequis

• Un accès administrateur au tableau de bord Ferndesk.

• Un accès administrateur ou développeur au code HTML de votre site web.

• Au moins un article publié dans votre centre d’aide (recommandé).

Avant de commencer

Vous pouvez intégrer le widget sur :

• Toutes les pages : ajoutez le script dans un modèle partagé ou un fichier d’en-tête (recommandé pour un accès global).

• Pages spécifiques : ajoutez le script uniquement aux pages où vous souhaitez afficher l’aide.

• Applications monopages (SPA) : ajoutez le script une seule fois dans votre mise en page principale ; il persistera lors de la navigation entre les pages.

Générez votre code d’intégration

1. Connectez-vous au tableau de bord Ferndesk.

2. Dans la barre latérale gauche, sous Centre d’aide, cliquez sur Widget.

3. Cliquez sur Installer sur la carte du widget que vous souhaitez intégrer. Chaque widget possède son propre code d’intégration et son propre ID de widget.

4. Cliquez sur le bouton Copier le code d’intégration pour copier l’intégralité de l’extrait dans votre presse-papiers.

Votre code d’intégration ressemblera à ceci :

<!-- Step #1. Install the Ferndesk SDK -->
<script>
    !(function (e, t) {
        var n = 'ferndesk-sdk',
            r = e.FERNDESK_SDK_SRC || 'https://static.ferndesk.com/dist/sdk.js',
            c = 'Ferndesk',
            s = t.currentScript;
        function a() {
            if (!t.getElementById(n)) {
                var e = t.createElement('script');
                ((e.id = n),
                    (e.src = r),
                    (e.async = !0),
                    s && s.nonce && ((e.nonce = s.nonce), e.setAttribute('nonce', s.nonce)));
                var c = t.getElementsByTagName('script')[0];
                c.parentNode.insertBefore(e, c);
            }
        }
        if ('function' != typeof e[c]) {
            var i = [],
                o = function () {
                    i.push(arguments);
                };
            ((o.q = i), (e[c] = o));
        }
        'complete' === t.readyState || 'interactive' === t.readyState
            ? a()
            : t.addEventListener('DOMContentLoaded', a);
    })(window, document);
</script>

<!-- Step #2. Initialize the widget -->
<script>
Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' })
</script>

Intégrez le widget à votre site

Pour un site web HTML standard

1. Ouvrez le fichier HTML principal de votre site web (souvent appelé index.html, un fichier de modèle ou un fichier d’inclusion d’en-tête/pied de page).

2. Repérez la balise fermante </body> vers la fin du fichier.

3. Collez l’intégralité du code d’intégration juste avant la balise </body> :

Pour une application React

1. Ouvrez votre mise en page principale ou le composant de votre application (par exemple, App.js ou _app.js dans Next.js).

2. Dans un hook useEffect, ajoutez le script d’intégration après le montage de votre composant :

import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    // Load the Ferndesk SDK
    const script = document.createElement('script');
    script.src = 'https://static.ferndesk.com/dist/sdk.js';
    script.async = true;
    document.body.appendChild(script);

    // Initialize the widget once the SDK loads
    script.onload = () => {
      window.Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' });
    };
  }, []);

  return (
    <>
      {/* Your app content */}
    </>
  );
}

Pour une application Vue

1. Ouvrez le fichier principal de votre application (par exemple, main.js ou App.vue).

2. Dans un hook de cycle de vie ou sous forme de script global, chargez et initialisez le widget :

import { onMounted } from 'vue';

export default {
  setup() {
    onMounted(() => {
      const script = document.createElement('script');
      script.src = 'https://static.ferndesk.com/dist/sdk.js';
      script.async = true;
      document.body.appendChild(script);

      script.onload = () => {
        window.Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' });
      };
    });
  }
};

Pour un générateur de site statique (Next.js, Gatsby, etc.)

1. Ajoutez le code d’intégration à votre mise en page ou à votre modèle de document.

2. Dans Next.js, utilisez le composant <Script> dans votre fichier _document.js ou votre mise en page :

import Script from 'next/script';

export default function Document() {
  return (
    <>
      <Script
        src="https://static.ferndesk.com/dist/sdk.js"
        strategy="afterInteractive"
        onLoad={() => {
          window.Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' });
        }}
      />
    </>
  );
}

Résoudre les problèmes d’intégration

Le bouton du widget ne s’affiche pas

• Vérifiez l’emplacement du script : assurez-vous que le script est placé dans le corps ou l’en-tête HTML, et non imbriqué dans des blocs conditionnels susceptibles d’empêcher son exécution.

• Vérifiez la console du navigateur : ouvrez les outils de développement de votre navigateur (F12 ou Cmd+Option+I) et recherchez les messages d’erreur dans l’onglet Console.

• Vérifiez les requêtes réseau : dans l’onglet Network des outils de développement, vérifiez que le script du SDK est chargé depuis https://static.ferndesk.com/dist/sdk.js. S’il est bloqué (il apparaît en rouge), vérifiez vos paramètres de sécurité ou votre pare-feu.

• Bloqueurs de publicités : certains bloqueurs de publicités peuvent empêcher le chargement du script Ferndesk. Essayez de désactiver les extensions et de recharger la page.

Le widget se charge, mais apparaît vide

• Attendez le chargement du contenu : sur les connexions lentes, le widget peut afficher brièvement une animation de chargement.

• Vérifiez le contenu du centre d’aide : assurez-vous d’avoir au moins un article publié dans votre centre d’aide Ferndesk. Une base de connaissances vide entraîne l’affichage d’un widget vide.

Le widget est chargé, mais son style semble incorrect

• Videz le cache du navigateur : votre navigateur utilise peut-être d’anciens fichiers du widget en cache. Videz le cache et rechargez la page (Ctrl+Maj+R sous Windows, Cmd+Maj+R sur Mac).

• Vérifiez les conflits CSS : assurez-vous que le CSS global de votre site ne remplace pas les styles du widget. Le widget utilise le Shadow DOM pour l’isolation, mais les règles globales peuvent tout de même l’affecter.

Le script du widget est bloqué par la Content Security Policy (CSP)

• Ajoutez-le à la liste blanche CSP : ajoutez https://static.ferndesk.com à la directive script-src de l’en-tête CSP.

• Exemple d’en-tête CSP : script-src 'self' https://static.ferndesk.com;

• Utilisez un nonce : si vous utilisez des nonces, le code d’intégration prend en charge les attributs nonce. Contactez l’assistance Ferndesk pour les configurations CSP avancées.

Personnalisation avancée via le SDK

Une fois intégré, vous pouvez contrôler le widget par programmation à l’aide du SDK Ferndesk. Par exemple :

• Ouvrir un article par programmation lors d’un clic sur un bouton.

• Masquer ou afficher le widget en fonction des actions de l’utilisateur.

• Déclencher une recherche depuis l’interface utilisateur de votre site.

• S’abonner aux événements du widget, tels que quickLinkClick. Les abonnements aux événements peuvent être mis en file d’attente avant le chargement du SDK et renvoient immédiatement une fonction de désabonnement.

Consultez la documentation du SDK Ferndesk pour obtenir tous les détails de l’API et des exemples de code.

Étapes suivantes

• Consultez la présentation du widget en libre-service pour découvrir toutes les fonctionnalités disponibles.

• Découvrez le SDK Ferndesk pour ajouter un contrôle par programmation.

• Consultez Utiliser les analyses du centre d’aide pour améliorer votre contenu pour suivre l’utilisation du widget.