So betten Sie das Self-Service-Widget ein

Das Self-Service-Widget wird mithilfe eines einfachen Skript-Snippets auf Ihrer Website eingebettet.

Nach dem Hinzufügen zu Ihrem HTML erscheint es auf allen Seiten, auf denen das Skript geladen wird, als schwebende Schaltfläche, über die Besucher sofort auf Ihr Hilfe-Center zugreifen können.

Voraussetzungen

• Administratorzugriff auf das Ferndesk-Dashboard.

• Administrator- oder Entwicklerzugriff auf das HTML oder den Code Ihrer Website.

• Mindestens ein veröffentlichter Artikel in Ihrem Hilfe-Center (empfohlen).

Bevor Sie beginnen

Sie können das Widget auf folgenden Seiten einbetten:

• Alle Seiten: Fügen Sie das Skript in eine gemeinsam verwendete Vorlage oder Header-Datei ein (empfohlen für den globalen Zugriff).

• Bestimmte Seiten: Fügen Sie das Skript nur auf bestimmten Seiten ein, auf denen die Hilfe angezeigt werden soll.

• Single-Page-Apps (SPAs): Fügen Sie das Skript einmal in Ihrem Hauptlayout ein. Es bleibt bei der Seitennavigation bestehen.

Einbettungscode generieren

1. Melden Sie sich beim Ferndesk-Dashboard an.

2. Klicken Sie in der linken Seitenleiste unter „Hilfe-Center“ auf Widget.

3. Klicken Sie auf der Karte des Widgets, das Sie einbetten möchten, auf Installieren. Jedes Widget verfügt über einen eigenen Einbettungscode und eine eigene Widget-ID.

4. Klicken Sie auf die Schaltfläche Einbettungscode kopieren, um das gesamte Snippet in Ihre Zwischenablage zu kopieren.

Ihr Einbettungscode sieht so aus:

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

<!-- Step #2. Initialize the widget -->
<script>
Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' })
</script>

Widget auf Ihrer Website einbetten

Für eine standardmäßige HTML-Website

1. Öffnen Sie die zentrale HTML-Datei Ihrer Website (häufig index.html, eine Vorlagendatei oder ein Header-/Footer-Include).

2. Suchen Sie das schließende Tag </body> in der Nähe des Dateiende.

3. Fügen Sie den gesamten Einbettungscode direkt vor dem Tag </body> ein:

Für eine React-Anwendung

1. Öffnen Sie Ihr Hauptlayout oder Ihre App-Komponente (z. B. App.js oder _app.js in Next.js).

2. Fügen Sie das Einbettungsskript in einem useEffect-Hook nach dem Mounten Ihrer Komponente hinzu:

import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    // Load the Ferndesk SDK
    const script = document.createElement('script');
    script.src = 'https://static.ferndesk.com/dist/sdk.js';
    script.async = true;
    document.body.appendChild(script);

    // Initialize the widget once the SDK loads
    script.onload = () => {
      window.Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' });
    };
  }, []);

  return (
    <>
      {/* Your app content */}
    </>
  );
}

Für eine Vue-Anwendung

1. Öffnen Sie Ihre zentrale App-Datei (z. B. main.js oder App.vue).

2. Laden und initialisieren Sie das Widget in einem Lifecycle-Hook oder als globales Skript:

import { onMounted } from 'vue';

export default {
  setup() {
    onMounted(() => {
      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' });
      };
    });
  }
};

Für einen statischen Website-Generator (Next.js, Gatsby usw.)

1. Fügen Sie den Einbettungscode zu Ihrem Layout oder Ihrer Dokumentvorlage hinzu.

2. Verwenden Sie für Next.js die Komponente <Script> in Ihrer Datei _document.js oder in Ihrem Layout:

import Script from 'next/script';

export default function Document() {
  return (
    <>
      <Script
        src="https://static.ferndesk.com/dist/sdk.js"
        strategy="afterInteractive"
        onLoad={() => {
          window.Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' });
        }}
      />
    </>
  );
}

Probleme beim Einbetten beheben

Die Widget-Schaltfläche wird nicht angezeigt

• Skriptplatzierung prüfen: Stellen Sie sicher, dass das Skript im HTML-Body oder -Head platziert ist und nicht in bedingten Blöcken verschachtelt ist, die die Ausführung verhindern könnten.

• Browserkonsole prüfen: Öffnen Sie die Entwicklertools Ihres Browsers (F12 oder Cmd+Option+I) und suchen Sie im Tab „Konsole“ nach Fehlermeldungen.

• Netzwerkanfragen prüfen: Überprüfen Sie im Tab „Netzwerk“ der Entwicklertools, ob das SDK-Skript von https://static.ferndesk.com/dist/sdk.js geladen wird. Wenn es blockiert wird (rot angezeigt), überprüfen Sie Ihre Sicherheitseinstellungen oder Firewall.

• Werbeblocker: Einige Werbeblocker können das Laden des Ferndesk-Skripts verhindern. Versuchen Sie, Erweiterungen zu deaktivieren und die Seite neu zu laden.

Das Widget wird geladen, bleibt aber leer

• Auf Inhalte warten: Bei langsamen Verbindungen zeigt das Widget möglicherweise kurz einen Ladekreisel an.

• Inhalte des Hilfe-Centers prüfen: Stellen Sie sicher, dass sich mindestens ein veröffentlichter Artikel in Ihrem Ferndesk-Hilfe-Center befindet. Eine leere Wissensdatenbank führt zu einem leeren Widget.

Das Widget wurde geladen, aber die Darstellung sieht fehlerhaft aus

• Browser-Cache leeren: Ihr Browser verwendet möglicherweise alte Widget-Dateien aus dem Cache. Leeren Sie den Cache und laden Sie die Seite neu (Strg+Umschalt+R unter Windows, Cmd+Umschalt+R auf dem Mac).

• CSS-Konflikte prüfen: Stellen Sie sicher, dass das globale CSS Ihrer Website die Stile des Widgets nicht überschreibt. Das Widget verwendet zur Isolierung das Shadow DOM, globale Regeln können es jedoch weiterhin beeinflussen.

Das Widget-Skript wird durch die Content Security Policy (CSP) blockiert

• Zur CSP-Allowlist hinzufügen: Fügen Sie https://static.ferndesk.com zur script-src-Direktive im CSP-Header hinzu.

• Beispiel für einen CSP-Header: script-src 'self' https://static.ferndesk.com;

• Eine Nonce verwenden: Wenn Sie Nonces verwenden, unterstützt der Einbettungscode Nonce-Attribute. Wenden Sie sich an den Ferndesk-Support, um Informationen zu erweiterten CSP-Konfigurationen zu erhalten.

Erweiterte Anpassung über das SDK

Nach dem Einbetten können Sie das Widget programmgesteuert über das Ferndesk-SDK steuern. Zum Beispiel:

• Einen Artikel programmgesteuert durch einen Klick auf eine Schaltfläche öffnen.

• Das Widget abhängig von Benutzeraktionen ausblenden oder anzeigen.

• Eine Suche über die Benutzeroberfläche Ihrer Website auslösen.

• Widget-Ereignisse wie quickLinkClick abonnieren. Ereignisabonnements können vor dem Laden des SDK in die Warteschlange eingereiht werden und geben sofort eine Funktion zum Beenden des Abonnements zurück.

Ausführliche API-Details und Codebeispiele finden Sie in der Ferndesk-SDK-Dokumentation.

Wie geht es weiter?

• Sehen Sie sich die Übersicht zum Self-Service-Widget an, um alle verfügbaren Funktionen kennenzulernen.

• Informieren Sie sich über das Ferndesk-SDK, um eine programmgesteuerte Steuerung hinzuzufügen.

• Sehen Sie sich Hilfe-Center-Analysen zur Verbesserung Ihrer Inhalte verwenden an, um die Nutzung des Widgets zu verfolgen.