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

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 das Widget initialisiert ist, erscheint es 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 (Ausblenden)

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 (Anzeigen)

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: Das Widget anzeigen, nachdem ein Benutzer eine bestimmte Aktion ausgeführt hat:

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

Open (Öffnen)

Öffnet das Widget-Hilfepanel programmgesteuert.

Ferndesk('open')

Parameter: Keine.

Rückgabewert: Keiner.

Verhalten: Öffnet das Hauptpanel 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ß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. Die Widget-Schaltfläche bleibt sichtbar und anklickbar.

Destroy (Zerstören)

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 (Identifizieren)

Authentifiziert und identifiziert einen Benutzer mit einem JWT-Token.

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

Parameter:

• token (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', { token: userToken });

Konsolenfehler:

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

• Ferndesk: identify failed - invalid token — 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.

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

Prefill (Vorausfüllen)

Füllt Kontaktformularfelder mit Benutzerdaten vor.

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

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.

Verhalten: Füllt automatisch Kontaktformularfelder aus, wenn der Benutzer das Kontaktformular öffnet. Gilt nur für leere Felder – überschreibt keine Benutzereingaben. Daten werden in die Warteschlange gestellt, wenn der Aufruf vor der Initialisierung erfolgt.

Beispiel — Vorausfüllen durch angemeldeten Benutzer:

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

Beispiel — Fehlermeldung:

// 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' Darstellung. Das Element, in dessen Nähe der Artikel verankert werden soll.

Rückgabewert: Keiner.

Präsentationsmodi:

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

• 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 Anchor-Elements ausgeklappt (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 Anchor 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 Short-ID der Sammlung aus Ihrem Hilfe-Center.

Rückgabewert: Keiner.

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

Beispiel — Fehlerbehebungs-Artikel durchsuchen:

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

Search (Suche)

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

Beispiel — Suche auslösen, wenn ein 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.

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>

Das Klicken auf diese Schaltfläche öffnet den Artikel mit der ID "help-123" im Hauptpanel des Widgets.

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 Sidebar-Modus, wenn darauf geklickt wird.

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

Klicken öffnet den Artikel in einer von der Seite einschiebbaren Sidebar.

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 Anchor 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 Isolierung: 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

Grundlegendes 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 in Ihre Website einbetten.

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