So betten Sie das Self-Service-Widget ein

Das Self-Service-Widget wird mit einem einfachen Script-Snippet in Ihre Website eingebettet.

Sobald es zu Ihrem HTML hinzugefügt wurde, erscheint es als schwebender Button auf allen Seiten, auf denen das Script geladen wird, sodass Besucher sofort auf Ihr Help Center zugreifen können.

Voraussetzungen

• Admin-Zugriff auf das Ferndesk-Dashboard.

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

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

Bevor Sie beginnen

Sie können das Widget einbetten auf:

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

• Bestimmte Seiten: Fügen Sie das Script nur auf bestimmten Seiten ein, auf denen Hilfe sichtbar sein soll.

• Single-Page-Apps (SPAs): Fügen Sie das Script einmal in Ihr Hauptlayout ein; es bleibt beim Navigieren zwischen Seiten erhalten.

Erstellen Sie Ihren Einbettungscode

1. Melden Sie sich im Ferndesk-Dashboard an.

2. Klicken Sie in der linken Seitenleiste unter Help Center auf Widget.

3. Klicken Sie auf die Schaltfläche Install Ihres Widgets.

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

Ihr Einbettungscode sieht dann 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>

Betten Sie das Widget in Ihre Website ein

Für eine Standard-HTML-Website

1. Öffnen Sie die Haupt-HTML-Datei Ihrer Website (oft index.html, eine Vorlagendatei oder ein Header-/Footer-Include genannt).

2. Suchen Sie das schließende </body>-Tag gegen Ende der Datei.

3. Fügen Sie den gesamten Einbettungscode direkt vor dem </body>-Tag 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 innerhalb eines useEffect-Hooks das Einbettungsskript hinzu, nachdem Ihre Komponente gemountet wurde:

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 Haupt-App-Datei (z. B. main.js oder App.vue).

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

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 Static-Site-Generator (Next.js, Gatsby usw.)

1. Fügen Sie den Einbettungscode zu Ihrem Layout oder Dokument-Template hinzu.

2. Für Next.js verwenden Sie die Komponente <Script> in Ihrer _document.js oder 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

Der Widget-Button wird nicht angezeigt

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

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

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

• Adblocker: Manche Adblocker können verhindern, dass das Ferndesk-Script geladen wird. Deaktivieren Sie testweise Erweiterungen und laden Sie die Seite neu.

Das Widget wird geladen, bleibt aber leer

• Auf Inhalte warten: Bei langsamen Verbindungen kann das Widget kurz einen Lade-Spinner anzeigen.

• Help-Center-Inhalte prüfen: Stellen Sie sicher, dass Sie mindestens einen veröffentlichten Artikel in Ihrem Ferndesk-Help-Center haben. Eine leere Wissensdatenbank führt zu einem leeren Widget.

Das Widget wurde geladen, aber die Formatierung sieht fehlerhaft aus

• Browser-Cache leeren: Möglicherweise speichert Ihr Browser alte Widget-Dateien zwischen. Leeren Sie den Cache und laden Sie die Seite neu (Ctrl+Shift+R unter Windows, Cmd+Shift+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 Shadow DOM zur Isolierung, aber globale Regeln können es dennoch beeinflussen.

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

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

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

• Einen Nonce verwenden: Wenn Sie Nonces verwenden, unterstützt der Einbettungscode Nonce-Attribute. Kontaktieren Sie den Ferndesk-Support für erweiterte CSP-Konfigurationen.

Erweiterte Anpassung über das SDK

Sobald es eingebettet ist, können Sie das Widget programmgesteuert mit dem Ferndesk-SDK steuern. Zum Beispiel:

• Öffnen Sie einen Artikel programmgesteuert über einen Button-Klick.

• Blenden Sie das Widget je nach Benutzeraktionen aus oder ein.

• Lösen Sie eine Suche über die UI Ihrer Website aus.

• Abonnieren Sie Widget-Ereignisse wie quickLinkClick. Ereignisabonnements können in die Warteschlange gestellt werden, bevor das SDK geladen ist, und geben sofort eine Funktion zum Aufheben des Abonnements zurück.

Weitere Informationen zu vollständigen API-Details und Codebeispielen finden Sie in der Ferndesk SDK-Dokumentation.

Wie geht es weiter

• Lesen Sie die Self-Service Widget Overview, um alle verfügbaren Funktionen zu sehen.

• Entdecken Sie das Ferndesk SDK, um die programmatische Steuerung hinzuzufügen.

• Sehen Sie sich Using Help Center Analytics to Improve Your Content an, um die Widget-Nutzung zu verfolgen.