Référence du SDK Ferndesk

Le SDK Ferndesk est une bibliothèque JavaScript légère qui permet un contrôle programmatique du Widget de Libre-service. Une fois intégré, il expose un objet global Ferndesk sur window.Ferndesk qui vous permet d'initialiser le widget, d'ouvrir des articles, de lancer des recherches et de gérer la visibilité, le tout depuis le code JavaScript de votre site.

Démarrage

Installation

Tout d'abord, intégrez le script du SDK Ferndesk dans votre HTML (ou copiez-le depuis le tableau de bord Ferndesk) :

<!-- 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>

Initialisation

Initialisez le widget avec votre identifiant de widget (widget ID) :

<script>
Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' })
</script>

Une fois initialisé, le widget apparaît sous forme de bouton flottant sur votre page, et toutes les méthodes du SDK deviennent disponibles.

Méthodes principales

Init

Initialise le widget Ferndesk.

Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID', open: true })

Paramètres :

• widgetId (chaîne, requis) : Votre identifiant de widget provenant du tableau de bord Ferndesk.

• open (booléen, facultatif) : Si vrai, le widget s'ouvre automatiquement au chargement de la page. Par défaut : faux.

• hideLauncher (booléen, facultatif) : Si vrai, masque le bouton flottant du widget. Le widget reste masqué jusqu'à ce que vous appeliez open() ou toggle(). Par défaut : faux.

Retourne : Rien. Déclenche l'initialisation du widget.

Exemple — Bouton d'aide personnalisé avec lanceur masqué :

<button onclick="Ferndesk('open')">Get Help</button>

<script>
Ferndesk('init', {
  widgetId: 'YOUR_WIDGET_ID',
  hideLauncher: true
});
</script>

Les utilisateurs cliquent sur votre bouton personnalisé pour ouvrir le widget. Le bouton flottant par défaut n'apparaît jamais.

Erreurs de console :

• Ferndesk: init requires a widgetId — Le paramètre widgetId est manquant.

• Ferndesk widget failed to load widget configuration — L'identifiant du widget est invalide ou introuvable.

Hide

Masque le bouton du widget et désactive l'interaction.

Ferndesk('hide')

Paramètres : Aucun.

Retourne : Rien.

Comportement : Masque le bouton du widget et ferme tous les panneaux ouverts. Les utilisateurs ne peuvent pas accéder au widget tant que show() n'est pas appelé.

Exemple d'utilisation : Masquer le widget sur les pages où l'aide n'est pas nécessaire :

if (window.location.pathname === '/checkout') {
  Ferndesk('hide');
}

Show

Affiche le bouton du widget et le rend interactif.

Ferndesk('show')

Paramètres : Aucun.

Retourne : Rien.

Comportement : Rend le bouton du widget visible. S'il est déjà visible, aucun changement ne se produit.

Exemple d'utilisation : Afficher le widget après qu'un utilisateur a effectué une certaine action :

document.getElementById('help-button').addEventListener('click', () => {
  Ferndesk('show');
});

Open

Ouvre le panneau d'aide du widget par programmation.

Ferndesk('open')

Paramètres : Aucun.

Retourne : Rien.

Comportement : Ouvre le panneau principal du widget sans naviguer vers un article spécifique. Les utilisateurs voient l'accueil du centre d'aide.

Exemple d'utilisation : Ouvrir l'aide lorsqu'un utilisateur clique sur un bouton "Obtenir de l'aide" :

document.getElementById('get-help').addEventListener('click', () => {
  Ferndesk('open');
});

Close

Ferme le panneau du widget ouvert.

Ferndesk('close')

Paramètres : Aucun.

Retourne : Rien.

Comportement : Ferme tout panneau, barre latérale ou modal du widget ouvert. Le bouton du widget reste visible et cliquable.

Destroy

Supprime complètement le widget et libère les ressources.

Ferndesk('destroy')

Paramètres : Aucun.

Retourne : Rien.

Comportement : Supprime le widget de la page, efface les écouteurs d'événements et réinitialise l'état. Pour utiliser de nouveau le widget, appelez init() avec un nouvel identifiant de widget.

Exemple d'utilisation : Nettoyer le widget lors du déchargement de la page dans les applications à page unique (SPA) :

window.addEventListener('beforeunload', () => {
  Ferndesk('destroy');
});

Identify

Authentifie et identifie un utilisateur avec un jeton JWT.

Ferndesk('identify', { token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' })

Paramètres :

• token (chaîne, requis) : Un jeton JWT signé contenant les informations d'identité de l'utilisateur.

Retourne : Rien.

Comportement : Authentifie l'utilisateur dans le widget, permettant un contenu d'aide personnalisé et une identification sécurisée. Le jeton doit être généré côté serveur et signé avec votre clé secrète Ferndesk.

Exemple — Identifier un utilisateur connecté :

// After user logs in, get JWT from your backend
const userToken = await fetch('/api/ferndesk-token').then(r => r.text());

Ferndesk('init', { widgetId: 'your-widget-id' });
Ferndesk('identify', { token: userToken });

Erreurs de console :

• Ferndesk: identify requires a token — Le paramètre token est manquant.

• Ferndesk: identify failed - invalid token — Le jeton JWT est mal formé ou la vérification de la signature a échoué.

• Ferndesk: identify must be called from the same domain or 1-level subdomain — Incohérence de domaine détectée.

Pour un guide complet sur l'implémentation de l'identification silencieuse JWT, consultez Identification silencieuse des utilisateurs par JWT.

Prefill

Pré-remplit les champs du formulaire de contact avec les données utilisateur.

Ferndesk('prefill', { name: 'Jane Doe', email: '[email protected]', subject: 'Billing Issue', message: 'Details here...' })

Paramètres : Objet avec des champs de chaîne facultatifs :

• name (chaîne, facultatif) : Nom de l'utilisateur

• email (chaîne, facultatif) : Adresse e-mail de l'utilisateur

• subject (chaîne, facultatif) : Objet du ticket

• message (chaîne, facultatif) : Corps du message

Retourne : Rien.

Comportement : Remplit automatiquement les champs du formulaire de contact lorsque l'utilisateur ouvre le formulaire. S'applique uniquement aux champs vides — n'écrasera pas la saisie de l'utilisateur. Les données sont mises en file d'attente si la méthode est appelée avant l'initialisation.

Exemple — Pré-remplissage à partir d'un utilisateur connecté :

Ferndesk('init', { widgetId: 'your-widget-id' });
Ferndesk('prefill', {
  name: user.fullName,
  email: user.email
});
Ferndesk('open');

Exemple — Rapport d'erreur :

// On crash page
Ferndesk('prefill', {
  subject: 'App Error',
  message: 'Error: ' + error.message
});
Ferndesk('open');

Avertissements de console :

• Ferndesk: 'prefill' ignored because the widget has not been initialised — Appelez init() d'abord.

Méthodes de navigation dans le contenu

OpenArticle

Ouvre un article spécifique dans le widget.

Ferndesk('openArticle', { shortId: 'help-123', presentation: 'widget' })

Paramètres :

• shortId (chaîne, requis) : La dernière partie de l'article.

• presentation (chaîne, facultatif) : Comment afficher l'article. Options : 'widget' (par défaut), 'sidebar', 'modal', 'inline'.

• anchor (élément HTML, facultatif) : Requis pour la présentation 'inline'. L'élément près duquel l'article doit être ancré.

Retourne : Rien.

Modes de présentation :

• widget (par défaut) : L'article s'ouvre à l'intérieur du widget d'aide principal.

• sidebar : L'article glisse depuis le bord droit sous forme de panneau latéral.

• modal : L'article s'ouvre dans une superposition plein écran centrée.

• inline : L'article s'agrandit près de l'élément d'ancrage (nécessite le paramètre anchor).

Exemple — Ouvrir un article dans un modal lors d'un clic sur un bouton :

document.getElementById('faq-button').addEventListener('click', () => {
  Ferndesk('openArticle', { shortId: 'faq-pricing', presentation: 'modal' });
});

Exemple — Ouvrir un article en ligne à côté d'un élément :

const anchorElement = document.getElementById('billing-info');
Ferndesk('openArticle', {
  shortId: 'billing-faq',
  presentation: 'inline',
  anchor: anchorElement
});

Erreurs de console :

• Ferndesk: openArticle requires a shortId — shortId est manquant.

• Ferndesk: Inline floating article requires an anchor element — presentation: 'inline' mais aucune ancre fournie.

• Ferndesk: openArticle ignored because the widget has not been initialised — init() n'a pas encore été appelé.

OpenCollection

Ouvre une collection spécifique dans le widget.

Ferndesk('openCollection', { shortId: 'getting-started' })

Paramètres :

• shortId (chaîne, requis) : L'identifiant court (short ID) de la collection provenant de votre centre d'aide.

Retourne : Rien.

Comportement : Ouvre la collection à l'intérieur du panneau d'aide du widget, affichant tous les articles de cette collection.

Exemple — Parcourir les articles de dépannage :

Ferndesk('openCollection', { shortId: 'xFqsqw' });

Search

Remplit la recherche du widget et affiche les résultats.

Ferndesk('search', { query: 'billing issues' })

Paramètres :

• query (chaîne, requis) : La requête de recherche. Doit être non vide.

Retourne : Rien.

Comportement : Ouvre le widget et affiche les résultats de recherche correspondant à la requête. Si aucun résultat ne correspond, affiche "Aucun résultat trouvé."

Exemple — Rechercher lorsqu'un utilisateur appuie sur une combinaison de touches :

document.addEventListener('keydown', (e) => {
  if (e.key === '?' && e.ctrlKey) {
    Ferndesk('search', { query: 'download videos' });
  }
});

Erreurs de console :

• Ferndesk: search requires a non-empty query — Le paramètre query est vide ou manquant.

Attributs de données pour déclencheurs en ligne

En plus des méthodes du SDK, vous pouvez utiliser des attributs de données HTML pour déclencher des actions du widget sans JavaScript :

data-ferndesk-article

Ouvre un article en mode widget lors d'un clic.

<button data-ferndesk-article="help-123">Learn More</button>

Cliquer sur ce bouton ouvre l'article avec l'ID "help-123" dans le panneau principal du widget.

data-ferndesk-article-modal

Ouvre un article en mode modal lors d'un clic.

<a href="#" data-ferndesk-article-modal="pricing-faq">View Pricing FAQs</a>

Cliquer sur ce lien ouvre l'article dans une superposition de modal centrée.

data-ferndesk-article-sidebar

Ouvre un article en mode barre latérale lors d'un clic.

<button data-ferndesk-article-sidebar="troubleshooting">Troubleshoot</button>

Cliquer ouvre l'article dans une barre latérale coulissante.

data-ferndesk-article-inline

Ouvre un article en mode en ligne ancré à l'élément cliqué.

<button id="my-button" data-ferndesk-article-inline="quick-help">Quick Help</button>

Cliquer sur ce bouton ouvre l'article en ligne près du bouton. Si aucune ancre n'est trouvée, la console du navigateur affiche un avertissement et bascule en mode modal.

Gestion des erreurs et journalisation

Le SDK consigne les erreurs et les avertissements dans la console du navigateur (non visible pour les utilisateurs finaux). Les messages courants incluent :

Conformité à la Politique de Sécurité du Contenu (CSP)

Si votre site utilise une Politique de Sécurité du Contenu (CSP) stricte, vous devrez peut-être autoriser le domaine Ferndesk :

Exemple d'en-tête CSP :

script-src 'self' https://static.ferndesk.com;

Considérations de performance

• Chargement asynchrone : Le script du SDK se charge de manière asynchrone en arrière-plan. Votre page continue de se charger pendant que le SDK s'initialise.

• Isolation par Shadow DOM : Le widget utilise le Shadow DOM pour encapsuler les styles et éviter les conflits avec le CSS de votre site.

• Chargement différé du contenu : Les articles et les résultats de recherche se chargent à la demande, et non tous en même temps.

• Aucun impact sur les performances : Le SDK ajoute une surcharge minimale, généralement moins de 50 Ko de JavaScript.

Exemples

Configuration de base

<html>
  <body>
    <!-- Your page content -->
    
    <script src="https://static.ferndesk.com/dist/sdk.js"></script>
    <script>
      Ferndesk('init', { widgetId: 'your-widget-id' });
    </script>
  </body>
</html>

Ouvrir un article au clic sur un bouton

<button id="help-btn">Get Help</button>

<script>
Ferndesk('init', { widgetId: 'your-widget-id' });

document.getElementById('help-btn').addEventListener('click', () => {
  Ferndesk('openArticle', {
    shortId: 'faq-overview',
    presentation: 'modal'
  });
});
</script>

Recherche sur saisie utilisateur

<input id="search-input" type="text" placeholder="Search help..."/>

<script>
Ferndesk('init', { widgetId: 'your-widget-id' });

document.getElementById('search-input').addEventListener('keypress', (e) => {
  if (e.key === 'Enter') {
    Ferndesk('search', { query: e.target.value });
  }
});
</script>

Aide contextuelle dans une application React

import { useEffect, useState } from 'react';

export default function App() {
  const [currentPage, setCurrentPage] = useState('home');

  useEffect(() => {
    // Initialize SDK
    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' });
    };
  }, []);

  useEffect(() => {
    // Hide widget on checkout page, show elsewhere
    if (currentPage === 'checkout') {
      window.Ferndesk('hide');
    } else {
      window.Ferndesk('show');
    }
  }, [currentPage]);

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

Et ensuite ?

• Découvrez comment intégrer le Widget de Libre-service sur votre site.

• Consultez l'Aperçu du Widget de Libre-service pour plus de détails sur les fonctionnalités.