Ferndesk SDK-Referenz

Das Ferndesk SDK ist eine schlanke JavaScript-Bibliothek, die programmatische Steuerung über das Self-Service-Widget ermöglicht. Nach dem Einbinden stellt es ein globales Ferndesk-Objekt unter window.Ferndesk bereit, mit dem Sie das Widget initialisieren, Artikel öffnen, Suchvorgänge auslösen und die Sichtbarkeit verwalten können – alles aus dem JavaScript-Code Ihrer Website heraus.

Erste Schritte

Installation

Binden Sie zunächst 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 schwebender Button auf Ihrer Seite, und alle SDK-Methoden werden verfügbar.

Kernmethoden

Init

Initialisiert 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 beim Laden der Seite automatisch. Standard: false.

• hideLauncher (boolean, optional): Wenn true, wird der schwebende Widget-Button ausgeblendet. Das Widget bleibt verborgen, bis Sie open() oder toggle() aufrufen. Standard: false.

• locale (string, optional): Legt die Sprache des Widgets über einen ISO 639-1 Sprachcode fest (z. B. 'fr', 'es', 'de'). Überschreibt die Spracherkennung des Browsers und die Standardwerte des Help Centers. Unterstützt: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr. Standard: automatisch vom Browser erkannt.

Rückgabewert: Keiner. Löst die Initialisierung des Widgets aus.

Beispiel — Benutzerdefinierter Hilfe-Button mit ausgeblendetem Launcher:

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

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

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

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

Nutzer klicken auf Ihren benutzerdefinierten Button, um das Widget zu öffnen. Der standardmäßige schwebende Button erscheint nie.

Konsolenfehler:

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

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

Ausblenden

Blendet den Widget-Button aus und deaktiviert die Interaktion.

Ferndesk('hide')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Blendet den Widget-Button aus und schließt alle geöffneten Bereiche. Nutzer können nicht auf das Widget zugreifen, bis show() aufgerufen wird.

Anwendungsbeispiel: Das Widget auf Seiten ausblenden, auf denen keine Hilfe benötigt wird:

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

Anzeigen

Zeigt den Widget-Button an und macht ihn interaktiv.

Ferndesk('show')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Macht den Widget-Button sichtbar. Wenn er bereits sichtbar ist, ändert sich nichts.

Anwendungsbeispiel: Das Widget anzeigen, nachdem ein Nutzer eine bestimmte Aktion ausgeführt hat:

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

Öffnen

Öffnet das Hilfepanel des Widgets programmgesteuert.

Ferndesk('open')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Öffnet das Hauptpanel des Widgets, ohne zu einem bestimmten Artikel zu navigieren. Nutzer sehen die Startseite des Help Centers.

Anwendungsbeispiel: Hilfe öffnen, wenn ein Nutzer auf einen „Hilfe erhalten“-Button klickt:

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

OpenHome

Setzt die Widget-Navigation auf die Startansicht zurück.

Ferndesk('openHome')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Öffnet das Widget und navigiert zur Startansicht. Wenn das Widget bereits geöffnet ist, aber eine andere Ansicht zeigt (z. B. den KI-Assistenten oder das Kontaktformular), wird die Navigation auf die Startansicht zurückgesetzt. Verwenden Sie dies, wenn Sie Nutzer aus einem beliebigen anderen Widget-Zustand zur Hauptansicht des Help Centers zurückbringen möchten.

// Button to reset widget to home view
document.getElementById('reset-help').addEventListener('click', () => {
  Ferndesk('openHome');
});

Wann verwenden:

• Sie möchten programmgesteuert aus einem anderen Widget-Zustand zur Startansicht zurückkehren.

• Sie benötigen eine zuverlässige Möglichkeit, die Widget-Navigation zurückzusetzen, unabhängig von der aktuellen Ansicht.

• Sie bauen eine benutzerdefinierte Navigation mit einer „Startseite“-Aktion.

OpenAssistant

Öffnet das Widget direkt in der Ansicht des KI-Assistenten.

Ferndesk('openAssistant')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Öffnet das Widget und navigiert direkt zur Chat-Ansicht des KI-Assistenten, in der Nutzer Fragen stellen und KI-gestützte Antworten aus Ihren Help-Center-Inhalten erhalten können. Verwenden Sie dies, wenn Nutzer sofort ein Gespräch mit dem KI-Assistenten beginnen sollen, statt Artikel zu durchsuchen.

Anwendungsbeispiel: Den KI-Assistenten über einen eigenen Button „Eine Frage stellen“ öffnen:

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

Anwendungsbeispiel: Den Assistenten über einen kontextbezogenen Hilfelink öffnen:

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

OpenContact

Öffnet das Widget direkt in der Ansicht des Kontaktformulars.

Ferndesk('openContact')

Parameter: Keine.

Rückgabewert: Keiner.

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

Anwendungsbeispiel: Das Kontaktformular über einen Button „Support kontaktieren“ öffnen:

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

Anwendungsbeispiel: Prefill mit openContact für angemeldete Nutzer kombinieren:

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

Schließen

Schließt das geöffnete Widget-Panel.

Ferndesk('close')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Schließt alle geöffneten Widget-Panels, Sidebars oder Modals. Der Widget-Button bleibt sichtbar und anklickbar.

Destroy

Entfernt das Widget vollständig und gibt Ressourcen frei.

Ferndesk('destroy')

Parameter: Keine.

Rückgabewert: Keiner.

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

Anwendungsbeispiel: Das Widget bei Seitenwechsel in Single-Page-Apps bereinigen:

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

SetLocale

Ändert die Sprache des Widgets nach der Initialisierung.

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: Wechselt die Benutzeroberfläche und die Inhalte des Widgets sofort in die angegebene Sprache. Lädt die Widget-Übersetzungen neu und ruft Inhalte in der neuen Sprache erneut ab. Übergeben Sie null, um die automatische sprachbasierte Erkennung des Browsers 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 Browsersprache zurücksetzen:

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

Identifizieren

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

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

Parameter:

• jwt (string, erforderlich): Ein signierter JWT-Token mit Informationen zur Nutzeridentität.

Rückgabewert: Keiner.

Verhalten: Authentifiziert den Nutzer im Widget und ermöglicht personalisierte Hilfeinhalte sowie eine sichere Identifizierung. Das Token muss serverseitig generiert und mit Ihrem Ferndesk-Geheimschlüssel signiert werden.

Beispiel — Angemeldeten Nutzer 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 zum Einrichten der stillen Nutzeridentifizierung finden Sie unter JWT Authentication.

Konsolenfehler:

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

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

• Ferndesk: identify must be called from the same domain or 1-level subdomain — Domänenabweichung erkannt.

Vorbefüllen

Sparen Sie Ihren Nutzern Zeit, indem Sie Name und E-Mail 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 Nutzer bereits angemeldet sind, warum sollten sie das Kontaktformular jedes Mal von Grund auf ausfüllen? Die Methode prefill füllt ihre Informationen automatisch aus und macht es ihnen leichter, schnell Hilfe zu erhalten.

Parameter: Objekt mit optionalen String-Feldern:

• name (string, optional): Name des Nutzers

• email (string, optional): E-Mail-Adresse des Nutzers

• subject (string, optional): Betreff der Anfrage

• message (string, optional): Nachrichtentext

Rückgabewert: Keiner.

Funktionsweise: Wenn der Nutzer das Kontaktformular öffnet, sind alle von Ihnen vorab ausgefüllten Felder bereits mit seinen Informationen belegt. Es werden nur leere Felder ausgefüllt, sodass nichts überschrieben wird, was er bereits eingegeben hat. Sie können prefill aufrufen, bevor die Initialisierung abgeschlossen ist; die Daten werden dann in die Warteschlange gestellt.

Beispiel — Details angemeldeter Nutzer automatisch ausfüllen:

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

Beispiel — Fehlermeldungen vorbefüllen:

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

Konsolenwarnungen:

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

Methoden zur Inhaltsnavigation

OpenArticle

Öffnet einen bestimmten Artikel im Widget.

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

Parameter:

• shortId (string, erforderlich): Der letzte Teil der Artikel.

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

• anchor (HTML-Element, optional): Erforderlich für die Darstellung 'inline'. Das Element, an dem der Artikel verankert werden soll.

Rückgabewert: Keiner.

Darstellungsmodi:

• widget (Standard): Der Artikel wird innerhalb des Haupt-Help-Widgets geöffnet.

• sidebar: Der Artikel gleitet vom rechten Rand als Seitenleiste hinein.

• modal: Der Artikel wird als zentrierte Vollbild-Überlagerung geöffnet.

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

Beispiel — Artikel per Klick auf einen Button in einem Modal ö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
});

Konsolenfehler:

• 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

Öffnet eine bestimmte Sammlung im Widget.

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

Parameter:

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

Rückgabewert: Keiner.

Verhalten: Öffnet die Sammlung im Hilfepanel des Widgets und zeigt alle Artikel in dieser Sammlung an.

Beispiel — Artikel zur Fehlerbehebung durchsuchen:

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

Search

Füllt die Widgetsuche und zeigt Ergebnisse an.

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

Parameter:

• query (string, erforderlich): Die Suchanfrage. Muss nicht leer sein.

Rückgabewert: Keiner.

Verhalten: Öffnet das Widget und zeigt Suchergebnisse an, die der Anfrage entsprechen. Wenn keine Ergebnisse übereinstimmen, wird „Keine Ergebnisse gefunden.“ angezeigt.

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

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

Konsolenfehler:

• Ferndesk: search requires a non-empty query — Die Suchanfrage 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 beim Klick einen Artikel im Widget-Modus.

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

Durch Klicken auf diesen Button wird der Artikel mit der ID „help-123“ im Hauptpanel des Widgets geöffnet.

data-ferndesk-article-modal

Öffnet beim Klick einen Artikel im Modus „Modal“.

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

Durch Klicken auf diesen Link wird der Artikel in einer zentrierten Modal-Überlagerung geöffnet.

data-ferndesk-article-sidebar

Öffnet beim Klick einen Artikel im Seitenleistenmodus.

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

Durch Klicken wird der Artikel in einer einblendenden Seitenleiste geöffnet.

data-ferndesk-article-inline

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

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

Durch Klicken auf diesen Button wird der Artikel inline in der Nähe des Buttons geöffnet. Wenn kein Anker gefunden wird, warnt die Browserkonsole und wechselt in den Modal-Modus.

Fehlerbehandlung und Protokollierung

Das SDK protokolliert Fehler und Warnungen in der Browserkonsole (nicht für Endnutzer sichtbar). Häufige Meldungen sind:

Compliance mit Content Security Policy (CSP)

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

Beispiel-CSP-Header:

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

Leistungsaspekte

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

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

• Lazy-Content-Laden: 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 per Klick auf einen Button ö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 Nutzereingabe

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

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

Ereignisse

Abonnieren Sie Widget-Ereignisse, um auf Nutzeraktionen auf Ihrer Website zu reagieren, indem Sie die Methode Ferndesk('on', event, handler) verwenden. Abonnements können vor der Initialisierung des Widgets in die Warteschlange gestellt werden und geben immer eine Unsubscribe-Funktion zurück.

On

Auf ein Widget-Ereignis abonnieren.

const unsubscribe = Ferndesk('on', 'quickLinkClick', (event) => {
  console.log('Link clicked:', event.label);
});

Parameter:

• event (string, erforderlich): Der Name des Ereignisses, für das Sie sich anmelden.

• handler (function, erforderlich): Die Callback-Funktion, die ausgeführt wird, wenn das Ereignis ausgelöst wird.

Rückgabewert: Eine unsubscribe-Funktion. Wenn Sie sie aufrufen, wird der Listener entfernt. Falls das SDK noch nicht geladen wurde, stellt die Funktion einen off-Aufruf in die Warteschlange, der automatisch ausgeführt wird, sobald das SDK bereit ist.

QuickLinkClick

Wird ausgelöst, wenn ein Besucher auf einen Schnelllink in der Startansicht des Widgets klickt.

Ferndesk('on', 'quickLinkClick', (event) => {
  if (event.id === 'custom-route') {
    event.preventDefault();
    history.pushState(null, '', event.url);
  }
});

Nutzlast:

• id (string): Die Link-ID.

• label (string): Die Bezeichnung des Links.

• url (string, optional): Das Ziel des Links.

• preventDefault() (function): Rufen Sie dies auf, um zu verhindern, dass das Widget zur Link-URL navigiert. Verwenden Sie dies, wenn Sie die Navigation selbst behandeln möchten.

• defaultPrevented (boolean, schreibgeschützt): true, wenn ein Handler preventDefault() aufgerufen hat.

Verhalten: Wenn preventDefault() nicht aufgerufen wird, folgt das Widget seinem normalen Linkverhalten (gleicher Tab oder neuer Tab, abhängig von der Einstellung In neuem Tab öffnen des Links). Modifizierte Klicks wie Strg-Klick, Umschalt-Klick und Mittelklick folgen immer dem Standardverhalten des Browsers.

Was kommt als Nächstes

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

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