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 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 dans le fichier d’en-tête (recommandé pour un accès global).

• Pages spécifiques : Ajoutez le script uniquement aux pages sur lesquelles vous souhaitez afficher l’aide.

• Applications à page unique (SPA) : Ajoutez le script une seule fois dans votre mise en page principale ; il persiste 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 le bouton Installer de votre widget.

4. Cliquez sur le bouton Copier le code d’intégration pour copier l’extrait complet 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 sur 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 include d’en-tête/pied de page).

2. Repérez 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 mise en page principale ou votre composant d’application (par ex. 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 ex. 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 dans 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 body ou le 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 Network 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é (affiché 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 s’affiche vide

• Attendez le chargement du contenu : Sur des 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 la page (Ctrl+Shift+R sous Windows, Cmd+Shift+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 quand même l’affecter.

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

• Ajoutez à la liste d’autorisation 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 inclut la prise en charge des 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 :

• Ouvrez un article par programmation à partir d’un clic sur un bouton.

• Masquez ou affichez le widget en fonction des actions de l’utilisateur.

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

• Abonnez-vous 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 renvoyer 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.

Et ensuite

• Consultez la présentation du widget en libre-service pour découvrir 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.