# Ferndesk SDK Reference The Ferndesk SDK is a lightweight JavaScript library that provides programmatic control over the Self-Service Widget. Once embedded, it exposes a global Ferndesk object on window.Ferndesk that allows you to initialize the widget, open articles, trigger searches, and manage visibility, all from your site's JavaScript code. Getting started Installation First, embed the Ferndesk SDK script in your HTML (or copy from the Ferndesk dashboard): Initialization Initialize the widget with your widget ID: Once initialized, the widget appears as a floating button on your page, and all SDK methods become available. The widgetId parameter is required. Core methods Init Initialize the Ferndesk widget. Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID', open: true }) Parameters: - widgetId (string, required): Your widget ID from the Ferndesk dashboard. - open (boolean, optional): If true, the widget opens automatically on page load. Default: false. - hideLauncher (boolean, optional): If true, hides the floating widget button. The widget stays hidden until you call open() or toggle(). Default: false. - locale (string, optional): Set the widget language using an ISO 639-1 language code (e.g., 'fr', 'es', 'de'). Overrides browser language detection and help center defaults. Supported: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr. Default: auto-detected from browser. Returns: None. Triggers widget initialization. Example — Custom help button with hidden launcher: Example — Force French language regardless of browser settings: Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID', locale: 'fr' }); Users click your custom button to open the widget. The default floating button never appears. If you set hideLauncher to true, make sure to provide another way for users to open the widget (like a custom button). Otherwise they won't be able to access your help center. Console errors: - Ferndesk: init requires a widgetId — widgetId parameter is missing. - Ferndesk widget failed to load widget configuration — The widget ID is invalid or not found. Hide Hide the widget button and disable interaction. Ferndesk('hide') Parameters: None. Returns: None. Behavior: Hides the widget button and closes any open panels. Users cannot access the widget until show() is called. Example use case: Hide the widget on pages where help isn't needed: if (window.location.pathname === '/checkout') { Ferndesk('hide'); } Show Display the widget button and make it interactive. Ferndesk('show') Parameters: None. Returns: None. Behavior: Makes the widget button visible. If already visible, no change occurs. Example use case: Show the widget after a user performs a certain action: document.getElementById('help-button').addEventListener('click', () => { Ferndesk('show'); }); Open Open the widget help panel programmatically. Ferndesk('open') Parameters: None. Returns: None. Behavior: Opens the main widget panel without navigating to a specific article. Users see the help center home. Example use case: Open help when a user clicks a "Get Help" button: document.getElementById('get-help').addEventListener('click', () => { Ferndesk('open'); }); Close Close the open widget panel. Ferndesk('close') Parameters: None. Returns: None. Behavior: Closes any open widget panel, sidebar, or modal. The widget button remains visible and clickable. Destroy Remove the widget completely and free resources. Ferndesk('destroy') Parameters: None. Returns: None. Behavior: Removes the widget from the page, clears event listeners, and resets state. To use the widget again, call init() with a new widget ID. Example use case: Clean up the widget on page unload in single-page apps: window.addEventListener('beforeunload', () => { Ferndesk('destroy'); }); SetLocale Change the widget language after initialization. Ferndesk('setLocale', 'es') Parameters: - locale (string or null, required): ISO 639-1 language code (e.g., 'de', 'ja') or null to reset to auto-detection. Returns: None. Behavior: Immediately switches the widget UI and content to the specified language. Reloads widget translations and re-fetches content in the new language. Pass null to restore automatic browser-based language detection. Supported languages: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr. Example — Language switcher: Example — Reset to browser language: // User clicks "Use my browser language" button Ferndesk('setLocale', null); The locale setting persists across page loads via localStorage. Users won't need to select their language again on return visits. Identify Authenticate and identify a user with a JWT token. Ferndesk('identify', { jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' }) Parameters: - jwt (string, required): A signed JWT token containing user identity information. Returns: None. Behavior: Authenticates the user in the widget, enabling personalized help content and secure identification. The token must be generated server-side and signed with your Ferndesk secret key. The identify method must be called from the same domain as your help center or from a 1-level subdomain (e.g., if your help center is at help.example.com, you can call identify from help.example.com or app.example.com, but not from different-domain.com). Example — Identify logged-in user: // 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 }); Call identify after init and before opening the widget. The token should include user ID, email, and any custom attributes you want to track. Console errors: - Ferndesk: identify requires a jwt — jwt parameter is missing. - Ferndesk: identify failed - invalid jwt — The JWT token is malformed or signature verification failed. - Ferndesk: identify must be called from the same domain or 1-level subdomain — Domain mismatch detected. For a complete guide on implementing silent JWT identification, see Silent JWT User Identification. Prefill Save your users time by auto-filling their name and email so they don't have to type it every time they contact you. Ferndesk('prefill', { name: 'Jane Doe', email: 'jane@example.com', subject: 'Billing Issue', message: 'Details here...' }) If your users are already logged in, why make them fill out the contact form from scratch? The prefill method automatically populates their information, making it easier for them to get help quickly. Parameters: Object with optional string fields: - name (string, optional): User's name - email (string, optional): User's email address - subject (string, optional): Ticket subject line - message (string, optional): Message body Returns: None. How it works: When the user opens the contact form, any fields you've prefilled will already have their information. It only fills empty fields, so it won't overwrite anything they've already typed. You can call prefill before init completes and the data will be queued. Prefill only works when your widget contact method is set to "form" (not "link"). Check your dashboard settings under Widget > Contact. Example — Auto-fill logged-in user details: Ferndesk('init', { widgetId: 'your-widget-id' }); Ferndesk('prefill', { name: user.fullName, email: user.email }); Ferndesk('open'); Example — Pre-populate error reports: // On crash page Ferndesk('prefill', { subject: 'App Error', message: 'Error: ' + error.message }); Ferndesk('open'); Call prefill after init but before opening the widget for best results. The prefilled data stays in place even if the user opens and closes the widget multiple times, but it clears after they submit the form. Console warnings: - Ferndesk: 'prefill' ignored because the widget has not been initialised — Call init() first. Content navigation methods OpenArticle Open a specific article in the widget. Ferndesk('openArticle', { shortId: 'help-123', presentation: 'widget' }) Parameters: - shortId (string, required): The last part of the article's. - presentation (string, optional): How to display the article. Options: 'widget' (default), 'sidebar', 'modal', 'inline'. - anchor (HTML element, optional): Required for 'inline' presentation. The element to anchor the article near. Returns: None. Presentation modes: - widget (default): Article opens inside the main help widget. - sidebar: Article slides in from the right edge as a side panel. - modal: Article opens in a centered full-screen overlay. - inline: Article expands near the anchor element (requires anchor parameter). Example — Open article in modal on button click: document.getElementById('faq-button').addEventListener('click', () => { Ferndesk('openArticle', { shortId: 'faq-pricing', presentation: 'modal' }); }); Example — Open article inline next to an element: const anchorElement = document.getElementById('billing-info'); Ferndesk('openArticle', { shortId: 'billing-faq', presentation: 'inline', anchor: anchorElement }); Console errors: - Ferndesk: openArticle requires a shortId — shortId is missing. - Ferndesk: Inline floating article requires an anchor element — presentation: 'inline' but no anchor provided. - Ferndesk: openArticle ignored because the widget has not been initialised — init() hasn't been called yet. OpenCollection Open a specific collection in the widget. Ferndesk('openCollection', { shortId: 'getting-started' }) Parameters: - shortId (string, required): The collection's short ID from your help center. Returns: None. Behavior: Opens the collection inside the widget help panel, displaying all articles in that collection. Example — Browse troubleshooting articles: Ferndesk('openCollection', { shortId: 'xFqsqw' }); Search Populate the widget search and display results. Ferndesk('search', { query: 'billing issues' }) Parameters: - query (string, required): The search query. Must be non-empty. Returns: None. Behavior: Opens the widget and displays search results matching the query. If no results match, displays "No results found." Example — Search when user presses a key combination: document.addEventListener('keydown', (e) => { if (e.key === '?' && e.ctrlKey) { Ferndesk('search', { query: 'download videos' }); } }); Console errors: - Ferndesk: search requires a non-empty query — query parameter is empty or missing. Data attributes for inline triggers In addition to SDK methods, you can use HTML data attributes to trigger widget actions without JavaScript: data-ferndesk-article Open an article in widget mode when clicked. Clicking this button opens the article with ID "help-123" in the main widget panel. data-ferndesk-article-modal Open an article in modal mode when clicked. View Pricing FAQs Clicking this link opens the article in a centered modal overlay. data-ferndesk-article-sidebar Open an article in sidebar mode when clicked. Clicking opens the article in a slide-in sidebar. data-ferndesk-article-inline Open an article in inline mode anchored to the clicked element. Clicking this button opens the article inline near the button. If no anchor is found, the browser console warns and falls back to modal mode. Error handling and logging The SDK logs errors and warnings to the browser console (not shown to end-users). Common messages include: Message Cause Solution Ferndesk: init requires a widgetId Missing widgetId parameter Provide your widget ID in the init call Ferndesk widget failed to load widget configuration Invalid or expired widget ID Verify the ID in the dashboard; regenerate if needed Ferndesk service not found SDK script didn't load (blocked by ad blocker, CSP, etc.) Check network requests; whitelist Ferndesk domain in CSP Ferndesk: search requires a non-empty query Empty or missing search query Provide a non-empty string for the query parameter Ferndesk: Inline floating article requires an anchor element Using inline presentation without anchor Provide an HTML element in the anchor parameter Ferndesk: 'method' ignored because the widget has not been initialised Called a method before init() completed Ensure init() is called before other methods (or wait for SDK load) Ferndesk: unknown command 'method' Called a non-existent method Check the method name and spelling against the SDK reference Content Security Policy (CSP) compliance If your site uses a strict Content Security Policy, you may need to allowlist the Ferndesk domain: Example CSP header: script-src 'self' https://static.ferndesk.com; If the SDK script is blocked by CSP, the console logs a CSP violation error. Add https://static.ferndesk.com to your script-src directive to allow it. Performance considerations The SDK uses asynchronous loading to avoid blocking page rendering. Typical load time is 200-500ms on a standard connection. - Async loading: The SDK script loads asynchronously in the background. Your page continues loading while the SDK initializes. - Shadow DOM isolation: The widget uses shadow DOM to encapsulate styles and prevent conflicts with your site's CSS. - Lazy content loading: Articles and search results load on demand, not all at once. - No performance impact: The SDK adds minimal overhead, typically less than 50KB of JavaScript. Examples Basic setup Open article on button click Search on user input Context-aware help in a 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 (

{/* Your page content */}

); } What's next - Learn how to embed the Self-Service Widget on your site. - Review the Self-Service Widget Overview for feature details.

Developers