Ferndesk SDK Referenz

Das Ferndesk SDK ist eine leichtgewichtige JavaScript-Bibliothek, die eine programmgesteuerte Steuerung des Self-Service-Widgets ermöglicht. Nach der Einbettung stellt es ein globales Ferndesk-Objekt unter window.Ferndesk zur Verfügung, mit dem Sie das Widget initialisieren, Artikel öffnen, Suchen auslösen und die Sichtbarkeit verwalten können – alles direkt aus dem JavaScript-Code Ihrer Website.

Erste Schritte

Installation

Zuerst betten Sie das Ferndesk SDK-Skript in Ihr HTML ein (oder kopieren Sie es aus dem Ferndesk Dashboard):

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

Initialisierung

Initialisieren Sie das Widget mit Ihrer Widget-ID:

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

Nach der Initialisierung erscheint das Widget als schwebende Schaltfläche auf Ihrer Seite, und alle SDK-Methoden stehen zur Verfügung.

Kernmethoden

Init

Initialisieren Sie das Ferndesk-Widget.

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

Parameter:

• widgetId (String, erforderlich): Ihre Widget-ID aus dem Ferndesk Dashboard.

• open (Boolean, optional): Wenn true, öffnet sich das Widget automatisch beim Laden der Seite. Standard: false.

• hideLauncher (Boolean, optional): Wenn true, wird die schwebende Widget-Schaltfläche ausgeblendet. Das Widget bleibt verborgen, bis Sie open() oder toggle() aufrufen. Standard: false.

• locale (String, optional): Legen Sie die Widget-Sprache mit einem ISO 639-1 Sprachcode fest (z. B. 'fr', 'es', 'de'). Überschreibt die Browser-Spracherkennung und die Standardeinstellungen des Help Centers. Unterstützt: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr. Standard: automatisch über den Browser erkannt.

Rückgabewert: Keiner. Löst die Widget-Initialisierung aus.

Beispiel — Benutzerdefinierte Hilfe-Schaltfläche mit ausgeblendetem Launcher:

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

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

Beispiel — Französische Sprache erzwingen, unabhängig von den Browsereinstellungen:

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

Benutzer klicken auf Ihre benutzerdefinierte Schaltfläche, um das Widget zu öffnen. Die standardmäßige schwebende Schaltfläche erscheint nie.

Konsole-Fehlermeldungen:

• Ferndesk: init requires a widgetId — Parameter widgetId fehlt.

• Ferndesk widget failed to load widget configuration — Die Widget-ID ist ungültig oder wurde nicht gefunden.

Hide

Verbergen Sie die Widget-Schaltfläche und deaktivieren Sie die Interaktion.

Ferndesk('hide')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Verbirgt die Widget-Schaltfläche und schließt alle geöffneten Panels. Benutzer können nicht auf das Widget zugreifen, bis show() aufgerufen wird.

Beispiel-Anwendungsfall: Widget auf Seiten ausblenden, auf denen keine Hilfe benötigt wird:

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

Show

Widget-Schaltfläche anzeigen und interaktiv machen.

Ferndesk('show')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Macht die Widget-Schaltfläche sichtbar. Falls sie bereits sichtbar ist, erfolgt keine Änderung.

Beispiel-Anwendungsfall: Widget anzeigen, nachdem ein Benutzer eine bestimmte Aktion ausgeführt hat:

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

Open

Das Widget-Hilfepanel programmgesteuert öffnen.

Ferndesk('open')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Öffnet das Haupt-Widget-Panel, ohne zu einem bestimmten Artikel zu navigieren. Benutzer sehen die Startseite des Help Centers.

Beispiel-Anwendungsfall: Hilfe öffnen, wenn ein Benutzer auf eine Schaltfläche „Hilfe anfordern“ klickt:

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

OpenAssistant

Das Widget direkt in der Ansicht des KI-Assistenten öffnen.

Ferndesk('openAssistant')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Öffnet das Widget und navigiert direkt zur Chat-Ansicht des KI-Assistenten, wo Benutzer Fragen stellen und KI-gestützte Antworten aus den Inhalten Ihres Help Centers erhalten können. Verwenden Sie dies, wenn Benutzer sofort ein Gespräch mit dem KI-Assistenten beginnen sollen, anstatt Artikel zu durchsuchen.

Beispiel-Anwendungsfall: KI-Assistenten über eine spezielle Schaltfläche „Eine Frage stellen“ öffnen:

document.getElementById('ask-question').addEventListener('click', () => {
  Ferndesk('openAssistant');
});

Beispiel-Anwendungsfall: Assistenten über einen kontextbezogenen Hilfe-Link öffnen:

<a href="#" onclick="Ferndesk('openAssistant')">Ask AI for help</a>

OpenContact

Das Widget direkt in der Ansicht des Kontaktformulars öffnen.

Ferndesk('openContact')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Öffnet das Widget und navigiert direkt zur Ansicht des Kontaktformulars, in der Benutzer eine Supportanfrage einreichen können. Das Verhalten des Kontaktformulars hängt von Ihren Widget-Einstellungen ab: Es kann ein E-Mail-Formular anzeigen, auf einen externen Link weiterleiten oder an eine integrierte Chat-Plattform wie Intercom oder Zendesk übergeben.

Beispiel-Anwendungsfall: Kontaktformular über eine Schaltfläche „Support kontaktieren“ öffnen:

document.getElementById('contact-support').addEventListener('click', () => {
  Ferndesk('openContact');
});

Beispiel-Anwendungsfall: Prefill mit openContact für angemeldete Benutzer kombinieren:

// After user clicks a "Report a problem" button
Ferndesk('prefill', {
  name: user.fullName,
  email: user.email,
  subject: 'Problem report'
});
Ferndesk('openContact');

Close

Das geöffnete Widget-Panel schließen.

Ferndesk('close')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Schließt jedes geöffnete Widget-Panel, die Seitenleiste oder das Modal. Die Widget-Schaltfläche bleibt sichtbar und anklickbar.

Destroy

Das Widget vollständig entfernen und Ressourcen freigeben.

Ferndesk('destroy')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Entfernt das Widget von der Seite, löscht Event-Listener und setzt den Status zurück. Um das Widget erneut zu verwenden, rufen Sie init() mit einer neuen Widget-ID auf.

Beispiel-Anwendungsfall: Widget beim Entladen der Seite in Single-Page-Apps bereinigen:

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

SetLocale

Die Widget-Sprache nach der Initialisierung ändern.

Ferndesk('setLocale', 'es')

Parameter:

• locale (String oder null, erforderlich): ISO 639-1 Sprachcode (z. B. 'de', 'ja') oder null, um zur automatischen Erkennung zurückzukehren.

Rückgabewert: Keiner.

Verhalten: Schaltet die Widget-Benutzeroberfläche und den Inhalt sofort in die angegebene Sprache um. Lädt Widget-Übersetzungen neu und ruft Inhalte in der neuen Sprache erneut ab. Übergeben Sie null, um die automatische browserbasierte Spracherkennung wiederherzustellen.

Unterstützte Sprachen: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr.

Beispiel — Sprachumschalter:

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

Beispiel — Zurücksetzen auf Browsersprache:

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

Identify

Authentifizieren und identifizieren Sie einen Benutzer mit einem JWT-Token.

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

Parameter:

• jwt (String, erforderlich): Ein signiertes JWT-Token, das Informationen zur Benutzeridentität enthält.

Rückgabewert: Keiner.

Verhalten: Authentifiziert den Benutzer im Widget und ermöglicht personalisierte Hilfeinhalte sowie eine sichere Identifizierung. Das Token muss serverseitig generiert und mit Ihrem Ferndesk Secret Key signiert werden.

Beispiel — Angemeldeten Benutzer identifizieren:

// 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 });

Eine vollständige Anleitung zur Einrichtung der stillen Benutzeridentifikation finden Sie unter JWT-Authentifizierung.

Konsole-Fehlermeldungen:

• Ferndesk: identify requires a jwt — Parameter jwt fehlt.

• Ferndesk: identify failed - invalid jwt — Das JWT-Token ist fehlerhaft oder die Signaturprüfung ist fehlgeschlagen.

• Ferndesk: identify must be called from the same domain or 1-level subdomain — Domain-Abweichung erkannt.

Prefill

Sparen Sie Ihren Benutzern Zeit, indem Sie deren Namen und E-Mail-Adresse automatisch ausfüllen, damit sie diese nicht jedes Mal eingeben müssen, wenn sie Sie kontaktieren.

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

Wenn Ihre Benutzer bereits angemeldet sind, warum sollten sie das Kontaktformular von Grund auf neu ausfüllen? Die prefill-Methode füllt deren Informationen automatisch aus und macht es ihnen so leichter, schnell Hilfe zu erhalten.

Parameter: Objekt mit optionalen String-Feldern:

• name (String, optional): Name des Benutzers

• email (String, optional): E-Mail-Adresse des Benutzers

• subject (String, optional): Betreffzeile des Tickets

• message (String, optional): Nachrichtentext

Rückgabewert: Keiner.

Funktionsweise: Wenn der Benutzer das Kontaktformular öffnet, enthalten alle von Ihnen vorausgefüllten Felder bereits deren Informationen. Es werden nur leere Felder ausgefüllt, sodass bereits eingegebene Daten nicht überschrieben werden. Sie können prefill aufrufen, bevor init abgeschlossen ist; die Daten werden dann in eine Warteschlange gestellt.

Beispiel — Details eines angemeldeten Benutzers automatisch ausfüllen:

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

Beispiel — Fehlermeldungen vorausfüllen:

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

Konsole-Warnungen:

• Ferndesk: 'prefill' ignored because the widget has not been initialised — Rufen Sie zuerst init() auf.

Inhaltsnavigationsmethoden

OpenArticle

Einen bestimmten Artikel im Widget öffnen.

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

Parameter:

• shortId (String, erforderlich): Der letzte Teil der Artikel-ID.

• presentation (String, optional): Wie der Artikel angezeigt werden soll. Optionen: 'widget' (Standard), 'sidebar', 'modal', 'inline'.

• anchor (HTML-Element, optional): Erforderlich für die Präsentation 'inline'. Das Element, in dessen Nähe der Artikel verankert werden soll.

Rückgabewert: Keiner.

Präsentationsmodi:

• widget (Standard): Der Artikel öffnet sich innerhalb des Haupt-Hilfe-Widgets.

• sidebar: Der Artikel wird von der rechten Seite als Seitenpanel eingeblendet.

• modal: Der Artikel öffnet sich in einem zentrierten Vollbild-Overlay.

• inline: Der Artikel wird in der Nähe des Ankerelements erweitert (erfordert den Parameter anchor).

Beispiel — Artikel in einem Modal bei Schaltflächenklick öffnen:

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

Beispiel — Artikel inline neben einem Element öffnen:

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

Konsole-Fehlermeldungen:

• Ferndesk: openArticle requires a shortId — shortId fehlt.

• Ferndesk: Inline floating article requires an anchor element — presentation: 'inline', aber kein Anker angegeben.

• Ferndesk: openArticle ignored because the widget has not been initialised — init() wurde noch nicht aufgerufen.

OpenCollection

Eine bestimmte Kollektion im Widget öffnen.

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

Parameter:

• shortId (String, erforderlich): Die Kurz-ID der Kollektion aus Ihrem Help Center.

Rückgabewert: Keiner.

Verhalten: Öffnet die Kollektion innerhalb des Widget-Hilfepanels und zeigt alle Artikel in dieser Kollektion an.

Beispiel — Fehlerbehebungsartikel durchsuchen:

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

Search

Die Widget-Suche füllen und Ergebnisse anzeigen.

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

Parameter:

• query (String, erforderlich): Der Suchbegriff. Darf nicht leer sein.

Rückgabewert: Keiner.

Verhalten: Öffnet das Widget und zeigt Suchergebnisse an, die dem Suchbegriff entsprechen. Wenn keine Ergebnisse gefunden werden, wird „Keine Ergebnisse gefunden“ angezeigt.

Beispiel — Suchen, wenn der Benutzer eine Tastenkombination drückt:

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

Konsole-Fehlermeldungen:

• Ferndesk: search requires a non-empty query — Parameter query ist leer oder fehlt.

Datenattribute für Inline-Trigger

Zusätzlich zu den SDK-Methoden können Sie HTML-Datenattribute verwenden, um Widget-Aktionen ohne JavaScript auszulösen:

data-ferndesk-article

Öffnet einen Artikel im Widget-Modus, wenn darauf geklickt wird.

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

Ein Klick auf diese Schaltfläche öffnet den Artikel mit der ID „help-123“ im Haupt-Widget-Panel.

data-ferndesk-article-modal

Öffnet einen Artikel im Modal-Modus, wenn darauf geklickt wird.

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

Ein Klick auf diesen Link öffnet den Artikel in einem zentrierten Modal-Overlay.

data-ferndesk-article-sidebar

Öffnet einen Artikel im Seitenleisten-Modus, wenn darauf geklickt wird.

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

Ein Klick öffnet den Artikel in einer einschwebenden Seitenleiste.

data-ferndesk-article-inline

Öffnet einen Artikel im Inline-Modus, verankert am angeklickten Element.

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

Ein Klick auf diese Schaltfläche öffnet den Artikel inline in der Nähe der Schaltfläche. Wenn kein Anker gefunden wird, warnt die Browser-Konsole und wechselt in den Modal-Modus.

Fehlerbehandlung und Protokollierung

Das SDK protokolliert Fehler und Warnungen in der Browser-Konsole (für Endbenutzer nicht sichtbar). Häufige Meldungen sind:

Content Security Policy (CSP) Konformität

Wenn Ihre Website eine strenge Content Security Policy verwendet, müssen Sie möglicherweise die Ferndesk-Domain auf die Whitelist setzen:

Beispiel für CSP-Header:

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

Performance-Aspekte

• Asynchrones Laden: Das SDK-Skript wird asynchron im Hintergrund geladen. Ihre Seite wird weiter geladen, während das SDK initialisiert wird.

• Shadow-DOM-Isolierung: Das Widget verwendet das Shadow DOM, um Stile zu kapseln und Konflikte mit dem CSS Ihrer Website zu vermeiden.

• Lazy-Loading von Inhalten: Artikel und Suchergebnisse werden bei Bedarf geladen, nicht alle auf einmal.

Beispiele

Grundlegende Einrichtung

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

Artikel bei Klick auf Schaltfläche öffnen

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

Suche bei Benutzereingabe

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

Kontextsensitive Hilfe in einer React-App

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>
  );
}

Nächste Schritte

• Erfahren Sie, wie Sie das Self-Service-Widget einbetten auf Ihrer Website.

• Lesen Sie die Übersicht über das Self-Service-Widget für Details zu den Funktionen.