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 auf window.Ferndesk bereit, mit dem Sie das Widget initialisieren, Artikel öffnen, Suchvorgänge auslösen und die Sichtbarkeit verwalten können – alles über den JavaScript-Code Ihrer Website.

Erste Schritte

Installation

Betten 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 schwebende Schaltfläche auf Ihrer Seite, und alle SDK-Methoden werden verfügbar.

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 unsichtbar, 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 wird nie angezeigt.

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.

Beispielfall: Ausblenden des Widgets auf Seiten, 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.

Beispielfall: Anzeigen des Widgets, 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.

Beispielfall: 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, jede Seitenleiste oder 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.

Beispielfall: Bereinigen des Widgets beim Entladen der Seite in Single-Page-Apps:

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 auf die automatische Erkennung zurückzusetzen.

Rückgabewert: Keiner.

Verhalten: Wechselt sofort die UI und den Inhalt des Widgets auf die angegebene Sprache. 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 eines Benutzers 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 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 stillen JWT-Identifizierung finden Sie unter Stille JWT-Benutzeridentifizierung.

Prefill

Sparen Sie Ihren Benutzern 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 Benutzer bereits angemeldet sind, warum sollten sie das Kontaktformular von Grund auf neu 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 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 Eingegebenes nicht überschrieben wird. Sie können prefill aufrufen, bevor init abgeschlossen ist; die Daten werden dann 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 — Fehlerberichte 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 des Artikels.

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

Darstellungsmodi:

• 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 wird in der Nähe des Ankerelements erweitert (erfordert den Parameter anchor).

Beispiel — Artikel bei Klick auf Schaltfläche im 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 Short-ID der Sammlung aus Ihrem Help Center.

Rückgabewert: Keiner.

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

Beispiel — Fehlerbehebungsartikel durchsuchen:

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

Search

Befü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 Anfrage passen. 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' });
  }
});

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 bei Klick einen Artikel im Widget-Modus.

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

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

data-ferndesk-article-modal

Öffnet bei Klick einen Artikel im Modal-Modus.

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

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

data-ferndesk-article-sidebar

Öffnet bei Klick einen Artikel im Seitenleisten-Modus.

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

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

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 (nicht für Endbenutzer sichtbar). Häufige Meldungen sind:

Einhaltung der Content Security Policy (CSP)

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

Beispiel CSP-Header:

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

Performance-Aspekte

• 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 Content Loading: Artikel und Suchergebnisse werden bei Bedarf geladen, nicht alle gleichzeitig.

• Keine Auswirkung 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>

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

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