Ferndesk SDK-Referenz

Das Ferndesk SDK ist eine schlanke JavaScript-Bibliothek, die die programmgesteuerte Steuerung des Self-Service-Widgets ermöglicht. Nach dem Einbinden 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 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 wird das Widget als schwebende Schaltfläche auf Ihrer Seite angezeigt, und alle SDK-Methoden sind verfügbar.

Der Parameter widgetId ist erforderlich.

Kernmethoden

Init

Das Ferndesk-Widget initialisieren.

Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID', open: true })

Parameter:

widgetId (string, erforderlich): Ihre Widget-ID aus dem Ferndesk-Dashboard.
open (boolean, optional): Wenn true, wird das Widget beim Laden der Seite automatisch geöffnet. Standard: false.
hideLauncher (boolean, optional): Wenn true, wird die schwebende Widget-Schaltfläche ausgeblendet. Das Widget bleibt ausgeblendet, bis Sie open() oder toggle() aufrufen. Standard: false.
locale (string, optional): Legt die Sprache des Widgets mithilfe eines ISO-639-1-Sprachcodes fest (z. B. 'fr', 'es', 'de'). Überschreibt die Erkennung der Browsersprache und die Standardeinstellungen des Hilfe-Centers. Unterstützt: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr. Standard: automatisch aus dem Browser erkannt.
changelogAnnouncements (boolean, optional): Steuert Ankündigungsaufforderungen für Changelog-Aktualisierungen. Ankündigungsaufforderungen werden nur identifizierten, angemeldeten Besuchern angezeigt. false unterdrückt Ankündigungsaufforderungen und Kennzeichnungen für ungesehene Einträge, während der Changelog-Feed und die direkte Navigation verfügbar bleiben. true wird akzeptiert, hat aber denselben Effekt wie das Weglassen der Option.
changelogAnnouncementTrigger (string, optional): Legt fest, ob eine geeignete Changelog-Ankündigung automatisch geöffnet wird. 'auto' (Standard) öffnet eine geeignete Ankündigung automatisch. 'manual' lässt die Kennzeichnung für ungesehene Einträge bestehen, überlässt das Öffnen der Ankündigung jedoch Ferndesk('showChangelogAnnouncement').

Rückgabe: Keine. Löst die Initialisierung des Widgets 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 unabhängig von den Browsereinstellungen erzwingen:

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.

Wenn Sie hideLauncher auf true setzen, stellen Sie sicher, dass Sie den Benutzern eine andere Möglichkeit zum Öffnen des Widgets bieten (z. B. eine benutzerdefinierte Schaltfläche). Andernfalls können sie nicht auf Ihr Hilfe-Center zugreifen.

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

Die Widget-Schaltfläche ausblenden und Interaktionen deaktivieren.

Ferndesk('hide')

Parameter: Keine.

Rückgabe: Keine.

Verhalten: Blendet die Widget-Schaltfläche aus und schließt alle geöffneten Bereiche. Benutzer können erst wieder auf das Widget zugreifen, wenn show() aufgerufen wird.

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

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

Anzeigen

Die Widget-Schaltfläche anzeigen und interaktiv machen.

Ferndesk('show')

Parameter: Keine.

Rückgabe: Keine.

Verhalten: Macht die Widget-Schaltfläche sichtbar. Wenn sie bereits sichtbar ist, tritt keine Änderung ein.

Beispielanwendungsfall: Das Widget anzeigen, nachdem ein Benutzer eine bestimmte Aktion ausgeführt hat:

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

Öffnen

Das Hilfe-Panel des Widgets programmgesteuert öffnen.

Ferndesk('open')

Parameter: Keine.

Rückgabe: Keine.

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

Beispielanwendungsfall: Hilfe öffnen, wenn ein Benutzer auf eine Schaltfläche „Hilfe erhalten“ klickt:

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

OpenHome

Die Widget-Navigation auf die Startansicht zurücksetzen.

Ferndesk('openHome')

Parameter: Keine.

Rückgabe: Keine.

Verhalten: Öffnet das Widget und navigiert zur Startansicht. Wenn das Widget bereits geöffnet ist, aber eine andere Ansicht anzeigt (z. B. den KI-Assistenten oder das Kontaktformular), wird die Navigation auf die Startansicht zurückgesetzt. Verwenden Sie dies, wenn Sie Benutzer aus einem anderen Widget-Zustand zurück zur Hauptansicht des Hilfe-Centers führen 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 unabhängig von der aktuellen Ansicht zurückzusetzen.
Sie erstellen eine benutzerdefinierte Navigation mit einer Aktion „Startseite“.

Der Befehl open öffnet das Widget bei geschlossenem Zustand in der Startansicht. Verwenden Sie openHome, wenn Sie aus einer anderen Ansicht wie dem KI-Assistenten oder dem Kontaktformular ausdrücklich zur Startseite zurücksetzen möchten.

OpenAssistant

Das Widget direkt in der Ansicht des KI-Assistenten öffnen.

Ferndesk('openAssistant')

Parameter: Keine.

Rückgabe: Keine.

Verhalten: Öffnet das Widget und navigiert direkt zur Chatansicht des KI-Assistenten, in der Benutzer Fragen stellen und KI-gestützte Antworten auf Grundlage der Inhalte Ihres Hilfe-Centers erhalten können. Verwenden Sie dies, wenn Benutzer sofort ein Gespräch mit dem KI-Assistenten beginnen sollen, anstatt Artikel zu durchsuchen.

Beispielanwendungsfall: Den KI-Assistenten über eine eigene Schaltfläche „Frage stellen“ öffnen:

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

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

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

OpenContact

Das Widget direkt in der Ansicht des Kontaktformulars öffnen.

Ferndesk('openContact')

Parameter: Keine.

Rückgabe: Keine.

Verhalten: Öffnet das Widget und navigiert direkt zur Ansicht des Kontaktformulars, über das Benutzer eine Supportanfrage senden 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 Chatplattform wie Intercom oder Zendesk übergeben.

Beispielanwendungsfall: Das Kontaktformular über eine Schaltfläche „Support kontaktieren“ öffnen:

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

Beispielanwendungsfall: Prefill mit openContact für angemeldete Benutzer kombinieren:

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

Der Befehl openContact berücksichtigt Ihre konfigurierte Kontaktmethode. Wenn Sie den Kontakt auf einen externen Link oder eine Integration eingestellt haben, leitet das Widget entsprechend weiter, anstatt ein E-Mail-Formular anzuzeigen.

Schließen

Das geöffnete Widget-Panel schließen.

Ferndesk('close')

Parameter: Keine.

Rückgabe: Keine.

Verhalten: Schließt alle geöffneten Widget-Panels, Seitenleisten oder Modalfenster. Die Widget-Schaltfläche bleibt sichtbar und anklickbar.

Destroy

Das Widget vollständig entfernen und Ressourcen freigeben.

Ferndesk('destroy')

Parameter: Keine.

Rückgabe: Keine.

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

Beispielanwendungsfall: Das Widget beim Entladen einer Seite in Single-Page-Apps bereinigen:

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

SetLocale

Die Sprache des Widgets nach der Initialisierung ändern.

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ückgabe: Keine.

Verhalten: Wechselt die Benutzeroberfläche und Inhalte des Widgets sofort in die angegebene Sprache. Lädt die Übersetzungen des Widgets neu und ruft die 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);

Die Spracheinstellung bleibt über localStorage hinweg über Seitenladevorgänge erhalten. Bei späteren Besuchen müssen Benutzer ihre Sprache nicht erneut auswählen.

Identify

Einen Benutzer mit einem JWT-Token authentifizieren und identifizieren.

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

Parameter:

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

Rückgabe: Keine.

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

Die identify-Methode muss von derselben Domain wie Ihr Hilfe-Center oder von einer Subdomain der ersten Ebene aufgerufen werden (wenn sich Ihr Hilfe-Center beispielsweise unter help.example.com befindet, können Sie identify von help.example.com oder app.example.com aufrufen, nicht jedoch von different-domain.com).

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

Rufen Sie identify nach init und vor dem Öffnen des Widgets auf. Das Token sollte die Benutzer-ID, die E-Mail-Adresse und alle benutzerdefinierten Attribute enthalten, die Sie verfolgen möchten.

Eine vollständige Anleitung zur Einrichtung der stillen Benutzeridentifizierung 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 – Eine Domainabweichung wurde festgestellt.

Prefill

Sparen Sie Ihren Benutzern Zeit, indem Sie deren Namen und E-Mail-Adresse 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 ausfüllen? Die Prefill-Methode trägt ihre Informationen automatisch ein und erleichtert ihnen so den schnellen Erhalt von Hilfe.

Parameter: Objekt mit optionalen Zeichenkettenfeldern:

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ückgabe: Keine.

Funktionsweise: Wenn der Benutzer das Kontaktformular öffnet, enthalten alle von Ihnen vorausgefüllten Felder bereits seine Informationen. Es werden nur leere Felder ausgefüllt, bereits eingegebene Inhalte werden nicht überschrieben. Sie können prefill aufrufen, bevor init abgeschlossen ist; die Daten werden dann in eine Warteschlange gestellt.

Prefill funktioniert nur, wenn die Kontaktmethode Ihres Widgets auf „form“ (nicht „link“) gesetzt ist. Prüfen Sie Ihre Dashboard-Einstellungen unter Widget > Contact.

Beispiel – Daten eines 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');

Rufen Sie prefill nach init, aber vor dem Öffnen des Widgets auf, um optimale Ergebnisse zu erzielen. Die vorausgefüllten Daten bleiben erhalten, auch wenn der Benutzer das Widget mehrmals öffnet und schließt, werden jedoch nach dem Absenden des Formulars gelöscht.

Konsolenwarnungen:

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

Methoden zur Inhaltsnavigation

OpenArticle

Einen bestimmten Artikel im Widget öffnen.

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

Parameter:

shortId (string, erforderlich): Der letzte Teil der Artikeladresse.
presentation (string, optional): Legt fest, wie der Artikel angezeigt wird. Optionen: 'widget' (Standard), 'sidebar', 'modal', 'inline'.
anchor (HTML-Element, optional): Für die Darstellung 'inline' erforderlich. Das Element, in dessen Nähe der Artikel verankert werden soll.

Rückgabe: Keine.

Darstellungsmodi:

widget (Standard): Der Artikel wird im Haupt-Hilfe-Widget geöffnet.
sidebar: Der Artikel wird vom rechten Rand als Seitenpanel eingeblendet.
modal: Der Artikel wird in einer zentrierten bildschirmfüllenden Überlagerung geöffnet.
inline: Der Artikel wird in der Nähe des Ankerelements erweitert (erfordert den Parameter anchor).

Beispiel – Artikel beim Klicken auf eine Schaltfläche in einem Modalfenster ö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

Eine bestimmte Sammlung im Widget öffnen.

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

Parameter:

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

Rückgabe: Keine.

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

Beispiel – Artikel zur Fehlerbehebung durchsuchen:

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

Search

Die Widget-Suche füllen und Ergebnisse anzeigen.

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

Parameter:

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

Rückgabe: Keine.

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

Changelog-Methoden

OpenChangelog

Einen Changelog im Widget öffnen.

Ferndesk('openChangelog')

Ferndesk('openChangelog', { shortId: 'abc123' })

Ferndesk('openChangelog', 'abc123')

Parameter:

shortId (string, optional): Die Kurz-ID des Changelogs, die als Objekteigenschaft oder als einfacher String übergeben wird. Ohne diesen Parameter öffnet das Widget den standardmäßigen sichtbaren Changelog des Besuchers.

Rückgabe: Keine.

Verhalten: Öffnet das Widget in der Changelog-Ansicht. Wenn kein sichtbarer Changelog vorhanden ist, führt der Befehl keine Aktion aus und protokolliert Ferndesk: This help center has no visible changelog.

GetChangelogStatus

Lesen, ob ein Changelog verfügbar ist und ungesehene Aktualisierungen enthält.

Ferndesk('getChangelogStatus')

Rückgabe: { available: boolean, unseen: boolean } oder null, bevor das Widget den Status gemeldet hat. available ist true, wenn ein Changelog für den aktuellen Besucher sichtbar ist; unseen ist true, wenn ein angekündigter Eintrag neuer ist als der vom Besucher zuletzt gesehene Stand.

ShowChangelogAnnouncement

Eine geeignete Changelog-Ankündigung auf Anfrage öffnen.

Ferndesk('showChangelogAnnouncement')

Parameter: Keine.

Verhalten: Öffnet die Ankündigung „Was gibt’s Neues?“ für einen angekündigten Eintrag, für den der Besucher berechtigt ist und den er noch nicht gesehen hat. Verwenden Sie dies mit changelogAnnouncementTrigger: 'manual': Das Widget meldet die ungesehene Ankündigung, überlässt das Öffnen jedoch diesem Befehl. Im Standardmodus 'auto' werden geeignete Ankündigungen automatisch geöffnet. Der Befehl führt keine Aktion aus, wenn der Besucher anonym ist, Ankündigungen deaktiviert sind oder der Besucher alle angekündigten Einträge gesehen hat.

Datenattribute für Inline-Trigger

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

data-ferndesk-article

Beim Klicken einen Artikel im Widget-Modus öffnen.

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

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

Beim Klicken einen Artikel im Modalmodus öffnen.

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

Beim Klicken auf diesen Link wird der Artikel in einer zentrierten modalen Überlagerung geöffnet.

data-ferndesk-article-sidebar

Beim Klicken einen Artikel im Seitenleistenmodus öffnen.

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

Beim Klicken wird der Artikel in einer eingeblendeten Seitenleiste geöffnet.

data-ferndesk-article-inline

Beim Klicken einen Artikel im Inline-Modus verankert am angeklickten Element öffnen.

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

Beim 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 Browserkonsole und es wird auf den Modalmodus zurückgegriffen.

data-ferndesk-changelog

Beim Klicken einen Changelog öffnen.

<button data-ferndesk-changelog>What's new</button>

Mit einem Wert ist dieser die Kurz-ID des Changelogs; ohne Wert öffnet das Widget den standardmäßigen Changelog des Besuchers. Wenn der Changelog-Status verfügbar ist und ungesehene Einträge vorliegen, zeigen passende Trigger einen kleinen Punkt als Kennzeichnung an.

Fehlerbehandlung und Protokollierung

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

Meldung	Ursache	Lösung
`Ferndesk: init requires a widgetId`	Fehlender widgetId-Parameter	Geben Sie Ihre Widget-ID im init-Aufruf an
`Ferndesk widget failed to load widget configuration`	Ungültige oder abgelaufene Widget-ID	Überprüfen Sie die ID im Dashboard und generieren Sie sie bei Bedarf neu
`Ferndesk service not found`	Das SDK-Skript wurde nicht geladen (z. B. durch einen Werbeblocker oder CSP blockiert)	Prüfen Sie die Netzwerkanfragen und setzen Sie die Ferndesk-Domain in der CSP auf die Allowlist
`Ferndesk: search requires a non-empty query`	Leere oder fehlende Suchanfrage	Übergeben Sie für den query-Parameter eine nicht leere Zeichenkette
`Ferndesk: Inline floating article requires an anchor element`	Inline-Darstellung ohne Anker verwendet	Geben Sie im anchor-Parameter ein HTML-Element an
`Ferndesk: 'method' ignored because the widget has not been initialised`	Eine Methode wurde vor Abschluss von init() aufgerufen	Stellen Sie sicher, dass init() vor anderen Methoden aufgerufen wird (oder warten Sie, bis das SDK geladen ist)
`Ferndesk: unknown command 'method'`	Eine nicht vorhandene Methode wurde aufgerufen	Überprüfen Sie Methodenname und Schreibweise anhand der SDK-Referenz

Konformität mit der Content Security Policy (CSP)

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

Beispiel für einen CSP-Header:

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

Wenn das SDK-Skript durch die CSP blockiert wird, protokolliert die Konsole einen CSP-Verletzungsfehler. Fügen Sie https://static.ferndesk.com Ihrer script-src-Direktive hinzu, um das Skript zuzulassen.

Überlegungen zur Leistung

Asynchrones Laden: Das SDK-Skript wird asynchron im Hintergrund geladen. Ihre Seite wird weiter geladen, während das SDK initialisiert wird.
Isolation durch Shadow DOM: Das Widget verwendet Shadow DOM, um Styles zu kapseln und Konflikte mit dem CSS Ihrer Website zu verhindern.
Verzögertes Laden von Inhalten: Artikel und Suchergebnisse werden bei Bedarf und nicht alle gleichzeitig geladen.

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 beim Klicken auf eine 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>

Bei Benutzereingabe suchen

<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 mit der Methode Ferndesk('on', event, handler) auf Benutzeraktionen auf Ihrer Website zu reagieren. Abonnements können vor der Initialisierung des Widgets in die Warteschlange gestellt werden und geben immer eine Funktion zum Abbestellen zurück.

On

Ein Widget-Ereignis abonnieren.

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

Parameter:

event (string, erforderlich): Der Name des Ereignisses, das abonniert werden soll.
handler (function, erforderlich): Die Callback-Funktion, die beim Auslösen des Ereignisses ausgeführt wird.

Rückgabe: Eine unsubscribe-Funktion. Durch ihren Aufruf wird der Listener entfernt. Wenn das SDK noch nicht geladen ist, stellt die Funktion einen off-Aufruf in die Warteschlange, der automatisch ausgeführt wird, sobald das SDK bereit ist.

Sie können Ferndesk('on', ...) aufrufen, bevor init() abgeschlossen ist. Das SDK führt die in die Warteschlange gestellten Befehle nach dem Laden in der richtigen Reihenfolge erneut aus.

QuickLinkClick

Wird ausgelöst, wenn ein Besucher im Widget auf der Startseite auf einen Schnelllink klickt.

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

Nutzdaten:

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 übernehmen möchten.
defaultPrevented (boolean, schreibgeschützt): true, wenn ein Handler preventDefault() aufgerufen hat.

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

ChangelogStatus

Wird ausgelöst, wenn sich die Verfügbarkeit oder der Status ungesehener Changelog-Einträge ändert.

Ferndesk('on', 'changelogStatus', ({ available, unseen }) => console.log(available, unseen))

Nutzdaten:

available (boolean): Gibt an, ob ein Changelog für den aktuellen Besucher sichtbar ist.
unseen (boolean): Gibt an, ob ein angekündigter Eintrag neuer ist als der vom Besucher zuletzt gesehene Stand.

Verhalten: Wird nach dem Start des Widgets und immer dann ausgelöst, wenn sich der Status ändert; identische Statuswerte werden nicht erneut ausgegeben.

ChangelogOpen

Wird ausgelöst, wenn die Changelog-Ansicht geöffnet wird.

Ferndesk('on', 'changelogOpen', ({ shortId }) => console.log(shortId))

Nutzdaten:

shortId (string oder null): Die Kurz-ID des geöffneten Changelogs.

Wie geht es weiter?

Erfahren Sie, wie Sie das Self-Service-Widget auf Ihrer Website einbinden.
Weitere Informationen zu den Funktionen finden Sie in der Übersicht zum Self-Service-Widget.

War das hilfreich?