Ferndesk SDK-Referenz

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

Erste Schritte

Installation

Binden Sie zuerst 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 mithilfe eines ISO 639-1 Sprachcodes 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 Browser-Einstellungen:

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.

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.

Hide

Blendet die Widget-Schaltfläche aus und deaktiviert die Interaktion.

Ferndesk('hide')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Blendet die Widget-Schaltfläche aus 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

Zeigt die Widget-Schaltfläche an und macht sie interaktiv.

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

Öffnet das Hilfe-Panel des Widgets programmgesteuert.

Ferndesk('open')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Öffnet das Haupt-Panel des Widgets, 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 erhalten“ klickt:

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

OpenHome

Widget-Navigation auf die Startansicht zurücksetzen.

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 (wie den KI-Assistenten oder das Kontaktformular), setzt dies die Navigation auf die Startansicht zurück. Verwenden Sie dies, wenn Sie Benutzer von jedem anderen Widget-Zustand zur Hauptansicht des Help Centers zurückführen möchten.

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

Wann zu 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 unabhängig von der aktuellen Ansicht zurückzusetzen.

• Sie erstellen eine benutzerdefinierte Navigation, die eine „Home“-Aktion enthält.

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 Benutzer Fragen stellen und KI-gestützte Antworten basierend auf 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: Den KI-Assistenten über eine dedizierte Schaltfläche „Eine Frage stellen“ öffnen:

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

Beispiel-Anwendungsfall: Den Assistenten über einen kontextbezogenen Hilfe-Link ö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 Benutzer 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.

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

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

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

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

Close

Schließt das geöffnete Widget-Panel.

Ferndesk('close')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Schließt alle geöffneten Widget-Panels, Sidebars oder Modale. Die Widget-Schaltfläche 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 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

Ändert die Widget-Sprache nach der Initialisierung.

Ferndesk('setLocale', 'es')

Parameter:

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

Rückgabewert: Keiner.

Verhalten: Schaltet die Widget-Benutzeroberfläche und den Inhalt sofort auf 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 Hilfe-Inhalte 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.

Konsolenfehler:

• Ferndesk: identify requires a jwt — Der 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 Name und E-Mail automatisch ausfüllen, damit sie diese nicht bei jeder Kontaktaufnahme erneut eingeben müssen.

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

So funktioniert es: Wenn der Benutzer das Kontaktformular öffnet, enthalten alle Felder, die Sie vorausgefüllt haben, bereits deren Informationen. Es werden nur leere Felder ausgefüllt, sodass bereits eingegebene Informationen nicht überschrieben werden. Sie können prefill aufrufen, bevor init abgeschlossen ist, und die Daten werden in die Warteschlange gestellt.

Beispiel — Details des 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');

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

• 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, in dessen Nähe der Artikel verankert werden soll.

Rückgabewert: Keiner.

Darstellungsmodi:

• widget (Standard): Der Artikel öffnet sich im Haupt-Hilfe-Widget.

• sidebar: Der Artikel wird vom rechten Rand als Seitenpanel eingeschoben.

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

• inline: Der Artikel erweitert sich in der Nähe des Anker-Elements (erfordert den Parameter anchor).

Beispiel — Artikel in einem Modal bei Klick auf eine Schaltfläche ö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 Hilfe-Panel des Widgets und zeigt alle Artikel in dieser Sammlung an.

Beispiel — Fehlerbehebungs-Artikel durchsuchen:

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

Search

Füllt die Widget-Suche aus und zeigt Ergebnisse an.

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

Parameter:

• query (String, erforderlich): Die Suchanfrage. Darf 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 — Suche, wenn der Benutzer 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 — Der query-Parameter ist leer oder fehlt.

Daten-Attribute für Inline-Trigger

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

data-ferndesk-article

Öffnet bei Klick einen Artikel im Widget-Modus.

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

Durch Klicken auf diese Schaltfläche wird der Artikel mit der ID „help-123“ im Haupt-Panel des Widgets geöffnet.

data-ferndesk-article-modal

Öffnet bei Klick einen Artikel im Modal-Modus.

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

Durch Klicken auf diesen Link wird der Artikel in einem zentrierten Modal-Overlay geöffnet.

data-ferndesk-article-sidebar

Öffnet bei Klick einen Artikel im Sidebar-Modus.

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

Durch Klicken wird der Artikel in einer einschiebbaren Sidebar geöffnet.

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>

Durch Klicken auf diese Schaltfläche wird der Artikel inline in der Nähe der Schaltfläche geöffnet. 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:

Einhaltung der Content Security Policy (CSP)

Wenn Ihre Website eine strikte 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;

Leistungsaspekte

• 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 Shadow DOM, um Stile zu kapseln und Konflikte mit dem CSS Ihrer Website zu vermeiden.

• Lazy Content Loading: Artikel und Suchergebnisse werden bei Bedarf geladen, nicht alle gleichzeitig.

Beispiele

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

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

Nächste Schritte

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

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