Référence SDK Ferndesk

Le SDK Ferndesk est une bibliothèque JavaScript légère qui permet un contrôle programmatique du widget de self-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 déclencher des recherches et de gérer la visibilité, le tout depuis le code JavaScript de votre site.

Prise en main

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 ID de widget :

<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

Initialiser le widget Ferndesk.

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

Paramètres :

• widgetId (string, requis) : Votre ID de widget provenant du tableau de bord Ferndesk.

• open (boolean, optionnel) : Si vrai, le widget s'ouvre automatiquement au chargement de la page. Par défaut : false.

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

• locale (string, optionnel) : Définit la langue du widget à l'aide d'un code de langue ISO 639-1 (ex : 'fr', 'es', 'de'). Remplace la détection de la langue du navigateur et les paramètres par défaut du centre d'aide. Langues supportées : en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr. Par défaut : détection automatique via le navigateur.

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>

Exemple — Forcer la langue française quels que soient les paramètres du navigateur :

Ferndesk('init', {
  widgetId: 'YOUR_WIDGET_ID',
  locale: 'fr'
});

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 de widget, barre latérale ou fenêtre modale ouverte. 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 ID 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');
});

SetLocale

Changer la langue du widget après l'initialisation.

Ferndesk('setLocale', 'es')

Paramètres :

• locale (string ou null, requis) : Code de langue ISO 639-1 (ex : 'de', 'ja') ou null pour revenir à la détection automatique.

Retourne : Rien.

Comportement : Bascule immédiatement l'interface et le contenu du widget vers la langue spécifiée. Recharge les traductions du widget et récupère le contenu dans la nouvelle langue. Passez null pour restaurer la détection automatique de la langue basée sur le navigateur.

Langues supportées : en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr.

Exemple — Sélecteur de langue :

<select id="lang-picker">
  <option value="en">English</option>
  <option value="fr">Français</option>
  <option value="es">Español</option>
</select>

<script>
document.getElementById('lang-picker').addEventListener('change', (e) => {
  Ferndesk('setLocale', e.target.value);
});
</script>

Exemple — Réinitialiser à la langue du navigateur :

// User clicks "Use my browser language" button
Ferndesk('setLocale', null);

Identify

Authentifier et identifier un utilisateur avec un jeton JWT.

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

Paramètres :

• jwt (string, 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 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, voir Identification silencieuse de l'utilisateur via JWT.

Prefill

Gagnez du temps pour vos utilisateurs en pré-remplissant leur nom et leur e-mail afin 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 prefill remplit automatiquement leurs informations, facilitant ainsi l'obtention d'aide rapide.

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

• name (string, optionnel) : Nom de l'utilisateur

• email (string, optionnel) : Adresse e-mail de l'utilisateur

• subject (string, optionnel) : Objet du ticket

• message (string, optionnel) : Corps du message

Retourne : Rien.

Comment ça marche : Lorsque l'utilisateur ouvre le formulaire de contact, tous les champs que vous avez pré-remplis contiendront déjà ses informations. Cela ne remplit que les champs vides, donc cela n'écrasera rien de ce qu'il a déjà saisi. Vous pouvez appeler prefill avant la fin de l'init 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 des 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 (string, requis) : La dernière partie de l'identifiant de l'article.

• presentation (string, optionnel) : Comment afficher l'article. Options : 'widget' (par défaut), 'sidebar', 'modal', 'inline'.

• anchor (HTML element, optionnel) : 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 comme un panneau latéral.

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

• 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 mode 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 — shortId est manquant.

• Ferndesk: Inline floating article requires an anchor element — presentation: 'inline' utilisé mais aucun ancrage fourni.

• 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 (string, requis) : L'identifiant court 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 (string, requis) : La requête de recherche. Ne doit pas être 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

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

Cliquer 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 aucun ancrage n'est trouvé, la console du navigateur émet un avertissement et repasse en mode modal.

Gestion des erreurs et journalisation

Le SDK consigne 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 (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 charger pendant que le SDK s'initialise.

• Isolation via 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, 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 de l'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 self-service sur votre site.

• Consultez la Présentation du widget de self-service pour plus de détails sur les fonctionnalités.