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 unter window.Ferndesk bereit, mit dem Sie das Widget initialisieren, Artikel öffnen, Suchen auslösen und die Sichtbarkeit verwalten können – alles ü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>

Sobald es initialisiert ist, erscheint das Widget als schwebende Schaltfläche 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 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.

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

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

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

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

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 offenen 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. Wenn 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 Hilfe-Centers.

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

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

Close

Schließt das geöffnete Widget-Panel.

Ferndesk('close')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Schließt jedes offene Widget-Panel, die Seitenleiste oder das Modal. 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: Bereinigen des Widgets beim Entladen der Seite in Single-Page-Apps:

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

Identify

Authentifiziert und identifiziert 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 });

Konsolenfehler:

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

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

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

Eine vollständige Anleitung zur Implementierung der Silent-JWT-Identifizierung finden Sie unter Silent JWT User Identification.

Prefill

Sparen Sie Ihren Benutzern Zeit, indem Sie deren Namen 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 automatisch deren Informationen aus und erleichtert ihnen so den schnellen Erhalt von Hilfe.

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 die von Ihnen vorausgefüllten Felder bereits deren Informationen. Es werden nur leere Felder ausgefüllt, sodass bereits eingegebene Texte 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 vorab ausfü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 'inline'-Anzeige. Das Element, in dessen Nähe der Artikel verankert werden soll.

Rückgabewert: Keiner.

Präsentationsmodi:

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

• sidebar: Der Artikel gleitet vom rechten Rand als Seitenpanel herein.

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

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

Beispiel — Artikel im Modal bei Klick auf 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 es wurde kein Anker bereitgestellt.

• 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 Hilfe-Center.

Rückgabewert: Keiner.

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

Beispiel — Fehlerbehebungsartikel durchsuchen:

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

Search

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

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 zur Abfrage passen. Wenn keine Ergebnisse übereinstimmen, wird "Keine Ergebnisse gefunden" angezeigt.

Beispiel — Suche auslösen, 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 Parameter query 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 einen Artikel im Widget-Modus, wenn darauf geklickt wird.

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

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

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

Das Klicken öffnet den Artikel in einer einblendbaren 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>

Das Klicken 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:

Einhaltung der Content Security Policy (CSP)

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

Beispiel für CSP-Header:

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

Leistungsaspekte

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

• Shadow DOM Isolation: Das Widget verwendet 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.

• Keine Auswirkungen auf die Performance: Das SDK verursacht minimalen Overhead, typischerweise weniger als 50 KB JavaScript.

Beispiele

Basis-Setup

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

Wie geht es weiter?

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