Comment intégrer le Widget de Self-Service

Le Widget de Self-Service s'intègre à votre site web à l'aide d'un simple extrait de script.

Une fois ajouté à votre HTML, il apparaît sous la forme d'un bouton flottant sur toutes les pages où le script se charge, permettant aux visiteurs d'accéder instantanément à votre centre d'aide.

Prérequis

• Accès administrateur au tableau de bord Ferndesk.

• Accès administrateur ou développeur au HTML ou au code 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 sur certaines pages où vous souhaitez que l'aide soit visible.

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

Générer 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 le bouton Installer de votre 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égrer le widget sur votre site

Pour un site web HTML standard

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

2. Recherchez la balise de fermeture </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 composant de mise en page ou d'application principal (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 votre fichier d'application principal (par exemple, main.js ou App.vue).

2. Dans un hook de cycle de vie ou en tant que 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. Pour Next.js, utilisez le composant <Script> dans votre _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' });
        }}
      />
    </>
  );
}

Dépannage des problèmes d'intégration

Le bouton du widget n'apparaît pas

• Vérifiez l'emplacement du script : Assurez-vous que le script est placé dans le corps (body) ou l'en-tête (head) du HTML, et non imbriqué dans des blocs conditionnels qui pourraient 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 des messages d'erreur dans l'onglet Console.

• Vérifiez les requêtes réseau : Dans l'onglet Réseau des outils de développement, vérifiez que le script SDK se charge depuis https://static.ferndesk.com/dist/sdk.js. S'il est bloqué (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 contenu : Sur les connexions lentes, le widget peut afficher brièvement un indicateur 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 un widget vide.

Le widget s'est chargé mais le style semble incorrect

• Videz le cache du navigateur : Votre navigateur peut mettre en cache d'anciens fichiers du widget. Videz le cache et rechargez (Ctrl+Shift+R sur Windows, Cmd+Shift+R sur Mac).

• Vérifiez les conflits CSS : Assurez-vous que le CSS global de votre site web n'écrase pas les styles du widget. Le widget utilise le shadow DOM pour l'isolation, mais les règles globales peuvent toujours l'affecter.

Le script du widget est bloqué par la politique de sécurité du contenu (CSP)

• Ajouter à la liste d'autorisation CSP : Ajoutez https://static.ferndesk.com à la directive script-src de votre en-tête CSP.

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

• Utiliser un nonce : Si vous utilisez des nonces, le code d'intégration inclut la prise en charge des attributs nonce. Contactez le support 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 à partir de l'interface utilisateur de votre site.

Consultez la documentation du SDK Ferndesk pour les détails complets de l'API et des exemples de code.

Et après ?

• Consultez l' Aperçu du Widget de Self-Service pour toutes les fonctionnalités disponibles.

• Explorez le SDK Ferndesk pour ajouter un contrôle programmatique.

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