Référence du SDK Ferndesk

Le SDK Ferndesk est une bibliothèque JavaScript légère qui permet de contrôler par programmation le Widget en 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 à partir du code JavaScript de votre site.

Prise en main

Installation

Tout d'abord, intégrez le script du SDK Ferndesk dans votre code 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 la forme d'un bouton flottant sur votre page, et toutes les méthodes du SDK deviennent disponibles.

Méthodes principales

Init

Initialiser le widget Ferndesk.

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

Paramètres :

• widgetId (chaîne, requis) : Votre widget ID 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 : false.

• 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 : false.

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'ID du widget est invalide ou introuvable.

Hide

Masquer le bouton du widget et désactiver 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

Afficher le bouton du widget et le rendre 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

Ouvrir 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

Fermer le panneau du widget ouvert.

Ferndesk('close')

Paramètres : Aucun.

Retourne : Rien.

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

Destroy

Supprimer complètement le widget et libérer 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 à 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 monopages (SPA) :

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

Identify

Authentifier et identifier un utilisateur avec un jeton JWT.

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

Paramètres :

• jwt (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 l'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', { jwt: userToken });

Erreurs de console :

• Ferndesk: identify requires a jwt — le paramètre jwt est manquant.

• Ferndesk: identify failed - invalid jwt — Le jeton JWT est malformé 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 JWT silencieuse, consultez Identification silencieuse de l'utilisateur par JWT.

Prefill

Faites gagner du temps à vos utilisateurs en pré-remplissant leur nom et leur adresse e-mail pour qu'ils n'aient pas à les saisir à chaque fois qu'ils vous contactent.

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

Si vos utilisateurs sont déjà connectés, pourquoi les obliger à remplir le formulaire de contact de zéro ? La méthode de pré-remplissage renseigne automatiquement leurs informations, ce qui leur permet d'obtenir de l'aide plus rapidement.

Paramètres : Objet avec des champs de type 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.

Fonctionnement : Lorsque l'utilisateur ouvre le formulaire de contact, tous les champs que vous avez pré-remplis contiendront déjà leurs informations. Elle ne remplit que les champs vides et n'écrasera donc rien de ce qu'ils ont déjà saisi. Vous pouvez appeler prefill avant que init ne soit terminé et les données seront mises en file d'attente.

Exemple — Pré-remplir les détails de l'utilisateur connecté :

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

Exemple — Pré-remplir les rapports 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

Ouvrir 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'identifiant 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 fenêtre superposée centrée en plein écran.

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

Exemple — Ouvrir un article en modal lors du 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 — le shortId est manquant.

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

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

OpenCollection

Ouvrir une collection spécifique dans le widget.

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

Paramètres :

• shortId (chaîne, requis) : Le 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

Alimenter la recherche du widget et afficher 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 quand l'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 les déclencheurs en ligne

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

data-ferndesk-article

Ouvrir un article en mode widget lors du 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

Ouvrir un article en mode modal lors du clic.

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

Cliquer sur ce lien ouvre l'article dans une fenêtre modale centrée.

data-ferndesk-article-sidebar

Ouvrir un article en mode barre latérale lors du clic.

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

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

data-ferndesk-article-inline

Ouvrir 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 repasse en mode modal.

Gestion des erreurs et journalisation

Le SDK enregistre les erreurs et les avertissements dans la console du navigateur (non visibles par 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 stricte, vous devrez peut-être ajouter le domaine Ferndesk à la liste blanche :

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 Shadow DOM : Le widget utilise le Shadow DOM pour encapsuler les styles et éviter les conflits avec le CSS de votre site.

• Chargement progressif du contenu : Les articles et les résultats de recherche se chargent à la demande, pas 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 lors de la 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>
  );
}

Étapes suivantes

• Découvrez comment intégrer le Widget en libre-service sur votre site.

• Consultez la Présentation du Widget en libre-service pour plus de détails sur les fonctionnalités.