How to embed the Self-Service Widget

The Self-Service Widget is embedded on your website using a simple script snippet.

Once added to your HTML, it appears as a floating button on all pages where the script loads, allowing visitors to access your help center instantly.

Prerequisites

• Admin access to the Ferndesk dashboard.

• Admin or developer access to your website's HTML or code.

• At least one published article in your help center (recommended).

Before you begin

You can embed the widget on:

• All pages: Add the script in a shared template or header file (recommended for global access).

• Specific pages: Add the script only to certain pages where you want help visible.

• Single-page apps (SPAs): Add the script once in your main layout; it persists across page navigation.

Generate your embed code

1. Log in to the Ferndesk dashboard.

2. In the left sidebar, select Widget.

3. Click on the Install button of your widget.

4. Click the Copy Embed Code button to copy the entire snippet to your clipboard.

Your embed code will look like this:

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

Embed the widget on your site

For a standard HTML website

1. Open your website's main HTML file (often called index.html, a template file, or a header/footer include).

2. Find the closing </body> tag near the end of the file.

3. Paste the entire embed code just before the </body> tag:

For a React application

1. Open your main layout or app component (e.g., App.js or _app.js in Next.js).

2. In a useEffect hook, add the embed script after your component mounts:

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

For a Vue application

1. Open your main app file (e.g., main.js or App.vue).

2. In a lifecycle hook or as a global script, load and initialize the widget:

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

For a static site generator (Next.js, Gatsby, etc.)

1. Add the embed code to your layout or document template.

2. For Next.js, use the <Script> component in your _document.js or 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' });
        }}
      />
    </>
  );
}

Troubleshooting embedding issues

The widget button isn't appearing

• Check script placement: Ensure the script is placed in the HTML body or head, not nested inside conditional blocks that might prevent execution.

• Check browser console: Open your browser's developer tools (F12 or Cmd+Option+I) and look for error messages in the Console tab.

• Check network requests: In the Network tab of developer tools, verify that the SDK script loads from https://static.ferndesk.com/dist/sdk.js. If it's blocked (shows red), check your security settings or firewall.

• Ad blockers: Some ad blockers may prevent the Ferndesk script from loading. Try disabling extensions and reloading the page.

The widget is loading but appears blank

• Wait for content: On slow connections, the widget may show a loading spinner briefly.

• Check help center content: Ensure you have at least one published article in your Ferndesk help center. An empty knowledge base results in a blank widget.

The widget loaded but styling looks off

• Clear browser cache: Your browser may be caching old widget files. Clear the cache and reload (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac).

• Check CSS conflicts: Ensure your website's global CSS isn't overriding the widget's styles. The widget uses shadow DOM for isolation, but global rules can still affect it.

The widget script is blocked by Content Security Policy (CSP)

• Add to CSP allowlist: Add https://static.ferndesk.com to your CSP header's script-src directive.

• Example CSP header: script-src 'self' https://static.ferndesk.com;

• Use a nonce: If using nonces, the embed code includes support for nonce attributes. Contact Ferndesk support for advanced CSP configurations.

Advanced customization via SDK

Once embedded, you can control the widget programmatically using the Ferndesk SDK. For example:

• Programmatically open an article from a button click.

• Hide or show the widget based on user actions.

• Trigger a search from your site's UI.

See the Ferndesk SDK documentation for complete API details and code examples.

What's next

• Review the Self-Service Widget Overview for all available features.

• Explore the Ferndesk SDK to add programmatic control.

• Check Using Help Center Analytics to Improve Your Content to track widget usage.