Widget-SDK
Das Widget-SDK ist die Befehlsfunktion window.Ferndesk, die das Einbettungssnippet auf Ihrer Seite installiert. Rufen Sie sie auf, um das Widget zu starten, Ansichten zu öffnen, Besucher anzumelden und auf Ereignisse im Widget zu reagieren.
Widget installieren
Kopieren Sie das Snippet Ihres Widgets aus dem Abschnitt „Installieren“ in Ferndesk. Es besteht aus zwei Teilen: Der erste lädt das SDK, der zweite startet Ihr Widget mit seiner ID. Kopieren Sie immer das vollständige Snippet aus Ferndesk. Es sieht so aus:
<!-- Step #1. Install the Ferndesk SDK -->
<script>
!function(e,t){ ... }(window,document);
</script>
<!-- Step #2. Initialize the widget -->
<script>
Ferndesk("init", { widgetId: "YOUR_WIDGET_ID" })
</script>Fügen Sie es direkt vor dem schließenden Tag </body> der Seiten ein, auf denen das Widget angezeigt werden soll. In Ferndesk gespeicherte Änderungen werden im Widget übernommen, ohne dass Sie diesen Code bearbeiten müssen.
Single-Page-Apps
Laden Sie das SDK einmal in Ihrem Root-Layout oder App-Shell. Das Widget bleibt auf der Seite, während Besucher zwischen Routen wechseln. Sie müssen init daher bei der Navigation nicht erneut aufrufen. Rufen Sie init nur dann erneut auf, wenn Sie eine damit festgelegte Option ändern möchten.
import { useEffect } from 'react';
export function FerndeskWidget() {
useEffect(() => {
if (document.getElementById('ferndesk-sdk')) return;
const script = document.createElement('script');
script.id = 'ferndesk-sdk';
script.src = 'https://static.ferndesk.com/dist/sdk.js';
script.async = true;
script.onload = () => {
window.Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' });
};
document.body.appendChild(script);
}, []);
return null;
}Rendern Sie die React-Komponente einmal in der Nähe des App-Roots.
Besucher anmelden
Wenn Ihre App weiß, wer der Besucher ist, übergeben Sie ein JWT, das mit dem Signing secret aus „Customer sign-in“ in Ihren Ferndesk-Entwicklereinstellungen signiert wurde. Das Widget zeigt dann Inhalte für diesen Kunden an und speichert dessen Chats unter seinem Konto. Die im Token enthaltenen Claims sind unter Leser mit JWT oder OIDC anmelden aufgeführt.
Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID', jwt: tokenFromYourServer });
// When the user signs in after the page loaded:
Ferndesk('identify', { jwt: tokenFromYourServer });
// When the user signs out:
Ferndesk('logout');Mit logout werden die Chats und das Kontaktformular des Besuchers aus diesem Browser gelöscht, damit die nächste Person an einem gemeinsam genutzten Computer sie nicht sieht. Alle Befehle und Optionen finden Sie in der Widget-SDK-Referenz.
Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' });
Ferndesk('openArticle', { shortId: 'abc123', presentation: 'modal' });Bei jedem Aufruf wird zuerst der Befehlsname übergeben, gefolgt von den Argumenten. Bei Befehlsnamen wird nicht zwischen Groß- und Kleinschreibung unterschieden.
Aufrufe, die vor dem Laden des SDK-Skripts erfolgen, werden in die Warteschlange gestellt und der Reihe nach ausgeführt, sobald das Skript geladen ist.
Ein unbekannter Befehl oder ein ungültiges Argument gibt eine Warnung in der Browserkonsole aus und ändert nichts.
Init-Optionen
Übergeben Sie diese Optionen an Ferndesk('init', { ... }). Nur widgetId ist erforderlich.
Option | Typ | Funktion | Standard |
|---|---|---|---|
| string | Die ID Ihres Widgets. Ohne sie gibt init eine Warnung aus und führt nichts aus. | Keine |
| boolean | Öffnet das Panel beim Laden des Widgets. |
|
| boolean | Blendet die schwebende Launcher-Schaltfläche aus. Stellen Sie Besuchern eine eigene Schaltfläche bereit, die |
|
| string oder null | Die Sprache des Besuchers, etwa | Ermittelt aus |
| string | Meldet den Besucher an, bevor das Widget eingebunden wird. Erwartet dasselbe Token wie | Anonym |
| boolean | Mit |
|
|
| Passt das Widget an das Design Ihrer Seite an. Bei | Eigene Einstellung des Widgets |
|
| Die Bildschirmseite, auf der Launcher und Panel auf dieser Seite angezeigt werden. | Die Position im Dashboard |
|
| Abstand zum seitlichen Rand ( | Der Rand im Dashboard |
|
| Überschreibt für diesen Besucher, wann eine Kontaktaufnahme mit einer Person angeboten wird: | Die Einstellung im Dashboard |
| boolean | Mit | Aktiv |
|
| Legt fest, wann eine Ankündigung angezeigt wird. Bei |
|
Ein erneuter Aufruf von
initentfernt das Widget und bindet ein neues ein. Das Panel wird geschlossen, der Besucher verliert seine Position undreadywird erneut ausgelöst.Single-Page-Apps müssen
initbei der Navigation nicht aufrufen. Das Widget bleibt auf der Seite, bisdestroyaufgerufen wird – auch wenn Ihr Router<body>ersetzt.Bei einem
initohnelocalebleibt die zuvor mitsetLocaleoder einem andereninitfestgelegte Sprache erhalten. AuchpageContextbleibt unverändert, bis ein weiteresiniteinen neuen Wert festlegt.<html data-ferndesk-context="off">hat dieselbe Wirkung wiepageContext: false.Bei Verwendung von
jwtwartet das Widget bis zu 3 Sekunden auf die Anmeldung, bevor es eingebunden wird. Danach wird es anonym eingebunden und übernimmt die Identität, sobald die Anmeldung abgeschlossen ist.Ankündigungen im Änderungsprotokoll werden nur angemeldeten Besuchern angezeigt und beziehen sich auf Einträge, die seit ihrem letzten Besuch angekündigt wurden. Anonyme Besucher und Erstbesucher werden nie unterbrochen.
Beispiel: Öffnen Sie das Widget über eine eigene Schaltfläche statt über den Launcher.
<button onclick="Ferndesk('open')">Get help</button>
<script>
Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID', hideLauncher: true });
</script>Position und Versatz
position und offset ersetzen die Position und den Rand des Dashboards nur auf dieser Seite. So erhält jede Umgebung die Platzierung, die ihr Code vorgibt.
Ferndesk('init', {
widgetId: 'YOUR_WIDGET_ID',
position: 'left',
offset: { x: 'calc(var(--sidebar-width, 264px) + 16px)', y: 24 }
});Jeder Teil ist optional. Für eine nicht angegebene Seite oder Achse wird der Dashboard-Wert beibehalten.
Für Versätze gibt es keinen Höchstwert. Das Widget kann daher neben der Seitenleiste Ihrer App oder über einer Fußzeile platziert werden.
Für CSS-Längen können Sie eigene benutzerdefinierte Eigenschaften verwenden, aber nur solche, die auf
:root,htmloderbodyfestgelegt sind. Der Container des Widgets ist ein untergeordnetes Element von<body>. Geben Sie der Variablen einen Fallback-Wert, wie im Beispiel gezeigt. Kann die Länge nicht aufgelöst werden, wird für diese Achse der Dashboard-Rand verwendet.Ungültige Werte werden mit einer Warnung ignoriert: eine unbekannte Seite, eine negative Zahl oder eine Zeichenfolge, die keine CSS-Längenangabe ist (z. B.
auto). Der Rest des Aufrufs wird weiterhin angewendet.Das Widget bleibt bedienbar. Der seitliche Versatz lässt mindestens 5rem des Ansichtsfensters für den Launcher frei, der untere Versatz mindestens 24rem, und das geöffnete Panel wird so verkleinert, dass es hineinpasst.
Auf Bildschirmen mit einer Breite unter 640px füllt das geöffnete Panel den Bildschirm aus. Versätze verschieben daher nur den Launcher.
Ändern Sie die Platzierung später mit
setLayout. Diese Optionen sind die unterstützte Möglichkeit, das Widget zu platzieren. Die internen CSS-Variablen--fd-*des Widgets sind nicht öffentlich und können sich ändern.
Befehle
Befehle, die einen Wert zurückgeben, liefern ihn sofort zurück. Ausnahmen sind identify und logout, die Promises zurückgeben.
Öffnen und schließen
Befehl | Argumente | Funktion |
|---|---|---|
| Keine | Öffnet das Panel. Ein mit |
| Keine | Schließt das Panel und alle schwebenden Artikel. |
| Keine | Öffnet das Panel, wenn es geschlossen ist, und schließt es, wenn es geöffnet ist. Wird ein schwebender Artikel angezeigt, wird stattdessen der Artikel geschlossen. |
| Keine | Blendet den Launcher und das Panel aus und schließt alle schwebenden Artikel. |
| Keine | Blendet ein mit |
| Keine | Öffnet das Panel auf der Startseite. |
| Keine | Gibt |
Jeder Befehl, der mit open beginnt, außer open selbst, sowie search blenden ein mit hide ausgeblendetes Widget ebenfalls wieder ein.
Zu Inhalten navigieren
Befehl | Argumente | Funktion |
|---|---|---|
| Optionaler Abschnitts-Slug als Zeichenfolge oder | Öffnet die Dokumentationsansicht und scrollt zu dem angegebenen Abschnitt. |
|
| Öffnet eine Sammlung. |
|
| Öffnet einen Artikel. Für |
|
| Öffnet das Widget mit Suchergebnissen für |
|
| Öffnet eine API-Referenz. |
|
| Öffnet einen Vorgang in einer API-Referenz. |
'inline' zeigt den Artikel neben dem Element an, das Sie als anchor übergeben. Ohne Anker wird stattdessen 'modal' verwendet.
Ferndesk('openArticle', {
shortId: 'billing-faq',
presentation: 'inline',
anchor: document.getElementById('billing-info')
});Ihr KI-Agent, Kontakt und Support-Unterhaltungen
Befehl | Argumente | Funktion |
|---|---|---|
| Keine | Öffnet den Chat mit Ihrem Agenten. Ist Support aktiviert, wird eine Unterhaltung gestartet. |
| Optional | Öffnet die für das Widget festgelegte Kontaktmöglichkeit: das Kontaktformular, einen Link, ein Chat-Tool oder WhatsApp. Mit |
| Keine | Öffnet den Tab „Nachrichten“ mit den Unterhaltungen des Besuchers. Funktioniert, wenn das Widget über einen Tab „Nachrichten“ verfügt. |
| Unterhaltungs-ID als Zeichenfolge oder | Öffnet die angegebene Unterhaltung. Gehört die ID nicht zu den Unterhaltungen des Besuchers, wird „Nachrichten“ geöffnet. Funktioniert, wenn das Widget über einen Tab „Nachrichten“ verfügt. |
| Optionaler Text als Zeichenfolge oder | Startet eine Unterhaltung mit dem Text im Eingabefeld. Der Besucher kann ihn lesen und senden. Funktioniert, wenn das Widget über einen Tab „Nachrichten“ verfügt. |
| Keine | Gibt die Anzahl der Antworten des Teams zurück, die der Besucher noch nicht gelesen hat. Gibt |
|
| Ändert die Eskalationsstrategie für diesen Besucher, wie es auch die Init-Option |
Ohne Support geben
openMessages,openConversationundopenNewMessageeine Warnung aus und öffnen die Startseite.Die Strategien entsprechen den Optionen unter Eine Person anbieten im Dashboard unter Ihr Agent > Anpassen > Übergabe:
'ai_decides'entspricht Bei Bedarf,'always_visible'entspricht Immer sichtbar und'none'entspricht Aus.Verwenden Sie eine besucherspezifische Strategie, um Kunden mit bevorzugtem Support eine Kontaktschaltfläche anzuzeigen oder bei einem Tarif ohne persönlichen Support keine Kontaktaufnahme mit einer Person anzubieten.
Ferndesk('init', {
widgetId: 'YOUR_WIDGET_ID',
jwt,
escalation: { strategy: user.plan === 'enterprise' ? 'always_visible' : 'ai_decides' }
});Identität und vorausgefüllte Felder
Befehl | Argumente | Funktion |
|---|---|---|
|
| Meldet den Besucher an, nachdem das Widget eingebunden wurde, oder aktualisiert seine Sitzung. Gibt ein Promise mit dem Ergebnis zurück. |
| Keine | Beendet die Help-Center-Sitzung, die das Widget gestartet hat. Entfernt den Support-Chat des Besuchers, die Unterhaltungsliste, vorausgefüllte Angaben und nicht gesendete Entwürfe aus diesem Browser. Das Widget bleibt für den nächsten anonymen Besucher auf der Seite. |
|
| Füllt leere Felder im Kontaktformular aus. Ein Aufruf vor |
Rufen Sie Ferndesk('logout') auf, wenn sich Ihr Nutzer abmeldet. Andernfalls sieht die nächste Person an einem gemeinsam genutzten Computer die Unterhaltungen des vorherigen Nutzers.
identify wird mit { identified: true, user } oder { identified: false, reason } aufgelöst.
const result = await Ferndesk('identify', { jwt });
if (!result.identified) {
console.warn('Ferndesk sign-in failed:', result.reason);
}Grund | Bedeutung |
|---|---|
| Es wurde kein JWT übergeben. |
|
|
| Das Help Center hat das JWT abgelehnt. |
| Es kam keine Antwort zurück, beispielsweise weil der Besucher offline ist. |
| Ein späterer Aufruf von |
Ein abgelehntes JWT für einen anderen Nutzer meldet den zuvor angemeldeten Nutzer ab. So zeigt das Widget niemals die Daten der vorherigen Person an.
Während ein
identify-Aufruf ausgeführt wird, wartet Support darauf, damit der Chat des Besuchers unter dem angemeldeten Nutzer gestartet wird.Läuft die Help-Center-Sitzung des Widgets ab, wird
identityExpiredausgelöst. Erstellen Sie ein neues JWT und rufen Sie erneutidentifyauf.
Im Kontaktformular eines angemeldeten Besuchers stehen zunächst der Name und die E-Mail-Adresse aus dem JWT. Bei Besuchern ohne JWT füllt prefill dieselben Felder aus; seine Werte haben Vorrang vor denen des JWT. Fügen Sie lockNameAndEmail: true hinzu, um Name und E-Mail-Adresse als eine schreibgeschützte Zeile anzuzeigen.
Ferndesk('prefill', {
name: user.fullName,
email: user.email,
lockNameAndEmail: true
});Jeder Aufruf ersetzt den vorherigen. Übergeben Sie daher jedes Mal Name und E-Mail-Adresse.
prefillfüllt nur leere Felder aus. Bereits vom Besucher eingegebene Inhalte werden nie ersetzt, auch keine zuvor verfasste, ungesendete Nachricht.Name und E-Mail-Adresse bleiben nach dem Senden erhalten. Ein vorausgefüllter
subjectund eine vorausgefülltemessagegelten für eine einzelne Nachricht und werden nach dem Senden gelöscht.Die E-Mail-Adresse wird außerdem in die E-Mail-Karte eines Support-Chats eingetragen, die nach einer Übergabe angezeigt wird. Der Besucher muss weiterhin auf „Senden“ klicken.
Bei einem angemeldeten Besucher sperrt
Ferndesk('prefill', { lockNameAndEmail: true })den Namen und die E-Mail-Adresse aus dem JWT.Nur ein nicht leerer Name und eine gültige E-Mail-Adresse werden gesperrt. Alles andere bleibt bearbeitbar, damit der Besucher immer eine Nachricht senden kann.
Die Sperre gilt nur für das Formular. Der Kontaktendpunkt akzeptiert weiterhin alle übermittelten Werte.
Meldet
identifyeine andere Person an, verwirft das Widget die vorausgefüllten Angaben, die Sperre, alle ungesendeten Nachrichten und die geöffneten Ansichten. Rufen Sieprefillfür die angemeldete Person auf, nachdemawait Ferndesk('identify', { jwt })aufgelöst wurde.
Darstellung und Layout
Befehl | Argumente | Funktion |
|---|---|---|
| Sprachcode oder | Ändert die Sprache des Widgets. Mit |
|
| Ändert das Farbschema passend zu Ihrer Seite. Mit |
|
| Ersetzt die Platzierung auf dieser Seite nach denselben Regeln wie bei |
Wenn Sie setLocale mit der Sprache aufrufen, die das Widget bereits anzeigt, geschieht nichts. Sie können den Befehl daher bei jedem Routenwechsel aufrufen, ohne ein geöffnetes Panel zu stören.
Änderungsprotokoll
Befehl | Argumente | Funktion |
|---|---|---|
| Optionale Short-ID als Zeichenfolge oder | Öffnet den Änderungsprotokoll-Feed. Ohne ID wird das für den Besucher sichtbare Änderungsprotokoll mit der neuesten Ankündigung geöffnet. Beim Öffnen eines Änderungsprotokolls werden dessen Einträge als gesehen markiert. |
| Optional | Zeigt den Ankündigungsbereich an, wenn der Besucher ungesehene Einträge hat. Andernfalls geschieht nichts. Verwenden Sie den Befehl mit |
| Keine | Gibt |
{ replay: true } ist für Ihre eigene Schaltfläche „Was gibt’s Neues?“. Damit wird jeder Klick beantwortet:
Ein Besucher mit ungesehenen Einträgen erhält den Ankündigungsbereich, den auch der automatische Auslöser anzeigen würde.
Ein Besucher, der alles gesehen hat oder noch keinen Eintrag als gesehen markiert hat, erhält die letzten drei angekündigten Veröffentlichungen.
Die Wiedergabe funktioniert für abgemeldete Besucher, bei deaktivierten Ankündigungen und mit beiden Auslösern. Ein ausgeblendetes Widget wird wieder eingeblendet.
Gibt es kein Änderungsprotokoll mit einer angekündigten Veröffentlichung, das der Besucher lesen kann, wird stattdessen der Änderungsprotokoll-Feed geöffnet.
whatsNewButton.addEventListener('click', () => {
Ferndesk('showChangelogAnnouncement', { replay: true });
});
Ferndesk('on', 'changelogStatus', ({ available, unseen }) => {
whatsNewButton.hidden = !available;
whatsNewButton.classList.toggle('has-news', unseen);
});Ereignisabonnements
Befehl | Argumente | Funktion |
|---|---|---|
| Ereignisname, Handler-Funktion | Registriert den Handler und gibt eine Funktion zurück, mit der Sie das Abonnement wieder aufheben können. Funktioniert vor dem Laden des SDK-Skripts und vor |
| Ereignisname, Handler-Funktion | Entfernt einen mit |
const off = Ferndesk('on', 'quickLinkClick', (link) => {
if (link.url?.includes('report-bug')) {
link.preventDefault();
openMyBugReportForm();
}
});
// later
off();Lebenszyklus
Befehl | Argumente | Funktion |
|---|---|---|
| Optionsobjekt | Bindet das Widget ein. Siehe Init-Optionen. |
| Keine | Entfernt das Widget von der Seite. Rufen Sie |
Ereignisse
Abonnieren Sie Ereignisse mit Ferndesk('on', event, handler). Der Handler erhält die unten aufgeführte Nutzlast.
Ereignis | Wird ausgelöst, wenn … | Nutzlast |
|---|---|---|
| das Widget seine Konfiguration geladen hat und gerendert werden kann. Wird einmal pro init-Aufruf ausgelöst. |
|
| das Panel auf dem Bildschirm erscheint – über den Launcher, einen Befehl oder | Keine |
| das Panel vom Bildschirm verschwindet: Der Besucher schließt es oder Sie rufen | Keine |
| ein Besucher auf einen benutzerdefinierten Link auf der Startseite klickt. |
|
| die Änderungsprotokollansicht auf einem beliebigen Weg geöffnet wird. |
|
| das Widget gestartet wird und sich der Status des Änderungsprotokolls ändert. |
|
| sich die Anzahl ungelesener Teamantworten ändert sowie einmal beim Start des Widgets. |
|
| die erste Nachricht des Besuchers eine Support-Unterhaltung startet. |
|
| der Besucher eine Nachricht sendet, auch die erste. |
|
| Ihr KI-Agent in einer Unterhaltung beginnt, eine Kontaktaufnahme mit einer Person anzubieten. |
|
| der Besucher in einer Kontaktaufforderung im Chat oder über den Kontaktlink auf der Startseite um eine Person bittet. |
|
| die Help-Center-Sitzung des Widgets abläuft. |
|
readyundunreadCountChangewerden einmal erneut an einen Handler gesendet, der erst nach ihrem Auslösen hinzugefügt wurde. Andere Ereignisse werden nicht erneut gesendet.openundclosewerden nur bei einer Zustandsänderung ausgelöst. Schwebende Artikel sind vom Panel unabhängig und lösen diese Ereignisse nicht aus.Bei
quickLinkClickverhindertpreventDefault()das Öffnen des Links durch das Widget, damit stattdessen Ihre Seite reagieren kann. Klicks mit einer Zusatztaste oder der mittleren Maustaste behalten das Browserverhalten bei und lösen das Ereignis nicht aus.changelogStatus.availableistfalse, wenn der Besucher kein Änderungsprotokoll sehen kann.unseenisttrue, solange es einen angekündigten Eintrag gibt, der neuer ist als der letzte Besuch des Besuchers. Für anonyme Besucher ist der Wert immerfalse.reasonist einer der folgenden Werte:'no_answer','partial','user_request','sensitive','negative_feedback'oder'frustrated'. BeiescalationRequestedist der Wertnull, wenn der Besucher den Link auf der Startseite verwendet hat.escalationOfferedwird pro Grund und Auslöser einmal je Unterhaltung ausgelöst. Die stets sichtbare Kontaktschaltfläche ist kein Angebot und löst das Ereignis nicht aus.
escalationRequested verarbeiten
Wenn escalationRequested ausgelöst wird, hat Ihr KI-Agent die Übergabenachricht bereits in draft und subject geschrieben. draft ist eine leere Zeichenfolge, wenn Übergabezusammenfassung entwerfen deaktiviert ist oder keine Unterhaltung zusammengefasst werden kann. source ist 'assistant' oder 'home'. channel gibt an, wohin das Widget den Besucher weiterleitet: { type: 'form' }, { type: 'link', url } oder { type: 'integration', platform }. Eine WhatsApp-Nummer wird als Link zu https://wa.me/<number> übergeben. Ihr Handler wählt eine von vier Möglichkeiten.
Aktion des Handlers | Aktion des Widgets |
|---|---|
Nichts | Die konfigurierte Übergabe, als wäre kein Handler vorhanden. |
| Zeigt ein Sheet im Widget mit Ihrem Text und Ihren Optionen an. |
| Leitet sofort weiter, optional über einen anderen Kanal oder mit einer anderen Nachricht. |
Nur | Nichts. Ihre Seite ist für den nächsten Schritt zuständig und kann später |
Ferndesk('on', 'escalationRequested', (event) => {
if (user.plan === 'basic') {
event.present({
title: 'Talk to our team',
message: 'Priority replies come with the Business plan.',
actions: [
{ label: 'Upgrade', url: '/billing/upgrade', target: 'self' },
{ label: 'Contact support anyway', action: 'continue' }
]
});
return;
}
if (event.trigger === 'billing_dispute') {
event.continue({
channel: { type: 'link', url: 'mailto:[email protected]' },
draft: `Plan: ${user.plan}\n\n${event.draft}`
});
}
});Eine Sheet-Aktion ist eine der folgenden Formen:
{ label, action: 'continue', channel, draft, subject }für die Übergabe, optional über einen anderen Kanal;{ label, url, target }für einen http(s)-, mailto- oder seiteninternen Link, wobeitarget: 'self'zur Navigation auf Ihrer Seite führt; oder{ label, onClick }, um Ihren Code auszuführen, während das Widget geöffnet bleibt.Jede Aktion kann optional
descriptionundstyle: 'primary' | 'secondary'enthalten. Standardmäßig ist die erste Aktion primär.Es werden höchstens vier Aktionen angezeigt. Unsichere URLs werden mit einer Warnung in der Konsole verworfen. Lassen Sie
actionsweg, um nur die Standardübergabe anzubieten.Um später zu entscheiden, rufen Sie innerhalb des Handlers
event.preventDefault()und anschließendpresent()odercontinue()auf, wenn Sie bereit sind. Nur der erste Aufruf voncontinue()wird berücksichtigt. Eine Anfrage ist nicht mehr gültig, sobald der Besucher erneut eine Anfrage stellt oder das Widget zerstört wird.continue()kann über{ type: 'link', url }oder{ type: 'integration', platform }zu einem anderen Kanal weiterleiten. Ein mailto-Link erhält den Entwurf als Betreff und Nachrichtentext, einwa.me- oderapi.whatsapp.com-Link als Chatnachricht. Bei allen anderen Seiten wird der Entwurf in die Zwischenablage kopiert.Unterstützte Integrationsplattformen sind
crisp,helpscout,intercom,zendesk,pylon,plainundchatwoot. Ist das Chat-Tool nicht auf der Seite verfügbar, verwendet das Widget ersatzweise die konfigurierte Kontaktmöglichkeit.Das Kontaktformular sendet Nachrichten an den im Dashboard festgelegten Posteingang. Es kann daher nur der Standardkanal sein, niemals ein Weiterleitungsziel.
triggerist der Schlüssel des Übergabeauslösers, auf den Ihr Agent reagiert hat, odernull. Definieren Sie Auslöser unter Ihr Agent > Anpassen > Übergabe, im Abschnitt Wann übergeben > Übergabeauslöser: beispielsweise einen Schlüssel wiebilling_disputeund eine Beschreibung in einfacher Sprache, wann er zutrifft.
Datenattribute
Fügen Sie diese Attribute zu beliebigen Elementen auf Ihrer Seite hinzu, um das Widget beim Klicken ohne JavaScript zu öffnen. Sie funktionieren, sobald init ausgeführt wurde.
Attribut | Was geöffnet wird |
|---|---|
| Die Dokumentationsansicht. Optional können Sie einen Abschnitts-Slug angeben, zu dem gescrollt werden soll. |
| Ein Artikel im Widget-Panel. |
| Ein Artikel in einer Seitenleiste. |
| Ein Artikel in einem Modal. |
| Ein Artikel neben dem angeklickten Element. |
| Eine API-Referenz. |
| Ein Vorgang in einer API-Referenz. |
| Der Änderungsprotokoll-Feed. Optional können Sie eine Short-ID des Änderungsprotokolls angeben. Ohne Angabe wählt das Widget dasselbe Änderungsprotokoll wie |
<button data-ferndesk-docs="billing">Billing help</button>
<a data-ferndesk-article-modal="abc123">Pricing FAQ</a>
<button data-ferndesk-api-operation="public-api/create-user">Create a user</button>
<button data-ferndesk-changelog>What's new</button>Artikelattribute akzeptieren auch eine Artikel-ID, die mit
art_beginnt.Das Widget wird nur bei einfachen Linksklicks geöffnet. Bei Klicks mit Cmd, Strg, Umschalt oder Alt bleibt das Browserverhalten erhalten.
Solange Besucher ungesehene Einträge im Änderungsprotokoll haben, fügt das SDK jedem Element mit
data-ferndesk-changelogeinen Punkt hinzu. Passen Sie dessen Darstellung mit CSS über.Ferndesk_BadgeContainer .Ferndesk_Badgean oder blenden Sie ihn aus und erstellen Sie mitchangelogStatusein eigenes Badge.
Unterstützte Sprachen
Die Benutzeroberfläche des Widgets ist in den folgenden Sprachen verfügbar. Verwenden Sie die Codes mit locale und setLocale.
Code | Sprache |
|---|---|
| Englisch |
| Französisch |
| Spanisch |
| Deutsch |
| Niederländisch |
| Portugiesisch |
| Italienisch |
| Japanisch |
| Koreanisch |
| Chinesisch |
| Schwedisch |
| Norwegisch |
| Dänisch |
| Finnisch |
| Türkisch |
| Estnisch |
Jedes BCP-47-Tag ist zulässig. Die Region wird ignoriert:
pt-BRsteht für Portugiesisch, undnbsowiennwerdennozugeordnet.Ein Code, für den das Widget keine Übersetzungen hat, wird ignoriert. Das Widget versucht es dann mit der nächsten Quelle:
<html lang>und anschließend der Browsersprache.Das Widget zeigt eine Sprache nur an, wenn sie in Ihrem Help Center aktiviert ist. Andernfalls wird die Standardsprache des Help Centers angezeigt. Ihr KI-Agent sucht und verlinkt Artikel in derselben Sprache.
Content Security Policy
Wenn Ihre Website eine Content Security Policy sendet, fügen Sie ihr diese Adressen hinzu. Einträge, die mit „Nur für bestimmte Widgets“ beginnen, sind nur erforderlich, wenn Ihr Widget die entsprechende Funktion verwendet.
Direktive | Hinzufügen | Verwendungszweck |
|---|---|---|
| Der Nonce-Wert Ihrer Seite im Snippet oder | Das SDK und die anderen Skripte des Widgets. Das Snippet überträgt seinen Nonce-Wert auf diese Skripte. Ohne Nonce müssen Sie den Host und einen Hash des Snippets zulassen. |
|
| Das Widget fügt seine Stile als |
|
| Die Schriftarten des Widgets. |
|
| Widget-Einstellungen, Ihr KI-Agent, Support-Chat und Änderungsprotokoll. |
| Die Adresse Ihres Help Centers: | Dokumentation, Suche und Artikel, die das Widget aus Ihrem Help Center abruft. |
|
| Widget-Analysen. Wenn Sie diese Adresse blockieren, bemerken Besucher keinen Unterschied, aber Ihre Widget-Berichte bleiben leer. |
|
| Dateien, die Besucher an einen Support-Chat anhängen. Sie werden direkt in den Cloudflare-R2-Speicher hochgeladen. |
|
| Logos, Teamfotos und Bilder in Artikeln und Einträgen des Änderungsprotokolls. |
|
| Nur für bestimmte Widgets: ein Widget-Header mit einem Unsplash-Hintergrund. |
|
| Nur für bestimmte Widgets: Phosphor-Symbole auf Widget-Links oder Karten. |
|
| Nur für bestimmte Widgets: HTML-Einbettungsblöcke in Artikeln und Einträgen des Änderungsprotokolls. |
| Der Video-Host, den Ihre Artikel einbetten, beispielsweise | Nur für bestimmte Widgets: Videoblöcke in Artikeln. |
| Alle anderen Hosts, die für Bilder in Ihren Artikeln verwendet werden | Nur für bestimmte Widgets: Bilder, die aus einem anderen Help Center importiert wurden, können weiterhin ihre ursprüngliche Adresse verwenden. |
Eine vollständige Richtlinie für ein Widget, dessen Help Center unter https://help.example.com verfügbar ist, mit einem Nonce-Wert im Snippet:
script-src 'nonce-<your nonce>';
style-src 'self' 'unsafe-inline' https://fonts.bunny.net;
font-src 'self' https://fonts.bunny.net;
img-src 'self' https://files.ferndesk.com;
connect-src 'self' https://engine.ferndesk.com https://help.example.com https://capture.ferndesk.com https://ferndesk-customer-private.4171fd55e47471c8b93a53e16a869f80.r2.cloudflarestorage.com;Beim Start des Chats meldet der Browser einen Verstoß gegen script-src 'unsafe-eval'. Er ist harmlos: Der Chat prüft, ob er Validatoren kompilieren darf, und funktioniert auch ohne sie. Fügen Sie 'unsafe-eval' nicht hinzu.
Ein Chat-Tool, an das das Widget weiterleitet, beispielsweise Intercom, Crisp oder Plain, benötigt eigene Adressen. Diese finden Sie in der Dokumentation des jeweiligen Tools.
Wenn das Widget nicht angezeigt wird
Prüfen Sie, ob das Snippet auf der Seite eingebunden ist: Öffnen Sie die Entwicklertools Ihres Browsers und suchen Sie nach einem Skript mit der ID
ferndesk-sdk.Prüfen Sie im Tab Netzwerk, ob
https://static.ferndesk.com/dist/sdk.jsgeladen wird. Werbeblocker und strenge Firewalls können das verhindern.Wenn Ihre Website eine Content Security Policy sendet, prüfen Sie, ob sie alle oben unter „Content Security Policy“ aufgeführten Adressen zulässt. Wird der Launcher angezeigt, bleibt das Widget aber leer, nennt die Konsole die blockierte Adresse.
Wenn die Konsole meldet, dass das SDK zweimal auf der Seite eingebunden ist, entfernen Sie das zweite Exemplar. Das passiert häufig, wenn sowohl ein Tag-Manager als auch ein fest eingebundenes Snippet das SDK laden. Das zuerst geladene Exemplar bleibt aktiv.