Referencia del SDK de Ferndesk

El SDK de Ferndesk es una biblioteca ligera de JavaScript que proporciona control programático sobre el Widget de Autoservicio. Una vez insertado, expone un objeto global Ferndesk en window.Ferndesk que te permite inicializar el widget, abrir artículos, activar búsquedas y gestionar la visibilidad, todo desde el código JavaScript de tu sitio.

Primeros pasos

Instalación

Primero, inserta el script del SDK de Ferndesk en tu HTML (o cópialo desde el panel de Ferndesk):

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

Inicialización

Inicializa el widget con tu ID de widget:

<script>
Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID' })
</script>

Una vez inicializado, el widget aparece como un botón flotante en tu página y todos los métodos del SDK quedan disponibles.

Métodos principales

Init

Inicializa el widget de Ferndesk.

Ferndesk('init', { widgetId: 'YOUR_WIDGET_ID', open: true })

Parámetros:

• widgetId (string, obligatorio): Tu ID de widget del panel de Ferndesk.

• open (boolean, opcional): Si es true, el widget se abre automáticamente al cargar la página. Por defecto: false.

• hideLauncher (boolean, opcional): Si es true, oculta el botón flotante del widget. El widget permanece oculto hasta que llames a open() o toggle(). Por defecto: false.

• locale (string, opcional): Establece el idioma del widget usando un código de idioma ISO 639-1 (p. ej., 'fr', 'es', 'de'). Invalida la detección de idioma del navegador y los valores predeterminados del centro de ayuda. Compatibles: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr. Por defecto: detección automática del navegador.

Retorna: Nada. Activa la inicialización del widget.

Ejemplo — Botón de ayuda personalizado con lanzador oculto:

<button onclick="Ferndesk('open')">Get Help</button>

<script>
Ferndesk('init', {
  widgetId: 'YOUR_WIDGET_ID',
  hideLauncher: true
});
</script>

Ejemplo — Forzar el idioma francés independientemente de la configuración del navegador:

Ferndesk('init', {
  widgetId: 'YOUR_WIDGET_ID',
  locale: 'fr'
});

Los usuarios hacen clic en tu botón personalizado para abrir el widget. El botón flotante por defecto nunca aparece.

Errores de consola:

• Ferndesk: init requires a widgetId — falta el parámetro widgetId.

• Ferndesk widget failed to load widget configuration — El ID del widget no es válido o no se encuentra.

Hide

Oculta el botón del widget y desactiva la interacción.

Ferndesk('hide')

Parámetros: Ninguno.

Retorna: Nada.

Comportamiento: Oculta el botón del widget y cierra cualquier panel abierto. Los usuarios no pueden acceder al widget hasta que se llame a show().

Ejemplo de uso: Ocultar el widget en páginas donde no se necesita ayuda:

if (window.location.pathname === '/checkout') {
  Ferndesk('hide');
}

Show

Muestra el botón del widget y lo hace interactivo.

Ferndesk('show')

Parámetros: Ninguno.

Retorna: Nada.

Comportamiento: Hace que el botón del widget sea visible. Si ya es visible, no ocurre ningún cambio.

Ejemplo de uso: Mostrar el widget después de que un usuario realice una acción determinada:

document.getElementById('help-button').addEventListener('click', () => {
  Ferndesk('show');
});

Open

Abre programáticamente el panel de ayuda del widget.

Ferndesk('open')

Parámetros: Ninguno.

Retorna: Nada.

Comportamiento: Abre el panel principal del widget sin navegar a un artículo específico. Los usuarios ven el inicio del centro de ayuda.

Ejemplo de uso: Abrir la ayuda cuando un usuario hace clic en un botón "Obtener ayuda":

document.getElementById('get-help').addEventListener('click', () => {
  Ferndesk('open');
});

Close

Cierra el panel del widget abierto.

Ferndesk('close')

Parámetros: Ninguno.

Retorna: Nada.

Comportamiento: Cierra cualquier panel, barra lateral o modal del widget que esté abierto. El botón del widget permanece visible y se puede hacer clic en él.

Destroy

Elimina el widget por completo y libera recursos.

Ferndesk('destroy')

Parámetros: Ninguno.

Retorna: Nada.

Comportamiento: Elimina el widget de la página, limpia los escuchadores de eventos y restablece el estado. Para usar el widget de nuevo, llama a init() con un nuevo ID de widget.

Ejemplo de uso: Limpiar el widget al descargar la página en aplicaciones de una sola página (SPA):

window.addEventListener('beforeunload', () => {
  Ferndesk('destroy');
});

SetLocale

Cambia el idioma del widget después de la inicialización.

Ferndesk('setLocale', 'es')

Parámetros:

• locale (string o null, obligatorio): código de idioma ISO 639-1 (p. ej., 'de', 'ja') o null para restablecer a la detección automática.

Retorna: Nada.

Comportamiento: Cambia inmediatamente la interfaz de usuario y el contenido del widget al idioma especificado. Recarga las traducciones del widget y vuelve a obtener el contenido en el nuevo idioma. Pasa null para restaurar la detección automática de idioma basada en el navegador.

Idiomas compatibles: en, fr, es, de, nl, pt, it, ja, ko, zh, sv, no, da, fi, tr.

Ejemplo — Selector de idioma:

<select id="lang-picker">
  <option value="en">English</option>
  <option value="fr">Français</option>
  <option value="es">Español</option>
</select>

<script>
document.getElementById('lang-picker').addEventListener('change', (e) => {
  Ferndesk('setLocale', e.target.value);
});
</script>

Ejemplo — Restablecer al idioma del navegador:

// User clicks "Use my browser language" button
Ferndesk('setLocale', null);

Identify

Autentica e identifica a un usuario con un token JWT.

Ferndesk('identify', { jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' })

Parámetros:

• jwt (string, obligatorio): Un token JWT firmado que contiene la información de identidad del usuario.

Retorna: Nada.

Comportamiento: Autentica al usuario en el widget, permitiendo contenido de ayuda personalizado e identificación segura. El token debe generarse en el servidor y firmarse con tu clave secreta de Ferndesk.

Ejemplo — Identificar usuario conectado:

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

Errores de consola:

• Ferndesk: identify requires a jwt — falta el parámetro jwt.

• Ferndesk: identify failed - invalid jwt — El token JWT está mal formado o la verificación de la firma falló.

• Ferndesk: identify must be called from the same domain or 1-level subdomain — Se detectó una discrepancia de dominio.

Para obtener una guía completa sobre cómo implementar la identificación silenciosa por JWT, consulta Identificación silenciosa de usuarios por JWT.

Prefill

Ahorra tiempo a tus usuarios rellenando automáticamente su nombre y correo electrónico para que no tengan que escribirlo cada vez que te contacten.

Ferndesk('prefill', { name: 'Jane Doe', email: '[email protected]', subject: 'Billing Issue', message: 'Details here...' })

Si tus usuarios ya han iniciado sesión, ¿por qué hacerles rellenar el formulario de contacto desde cero? El método prefill rellena automáticamente su información, facilitándoles obtener ayuda rápidamente.

Parámetros: Objeto con campos de cadena opcionales:

• name (string, opcional): Nombre del usuario

• email (string, opcional): Correo electrónico del usuario

• subject (string, opcional): Línea de asunto del ticket

• message (string, opcional): Cuerpo del mensaje

Retorna: Nada.

Cómo funciona: Cuando el usuario abre el formulario de contacto, cualquier campo que hayas pre-rellenado ya tendrá su información. Solo rellena campos vacíos, por lo que no sobrescribirá nada que ya hayan escrito. Puedes llamar a prefill antes de que init termine y los datos se pondrán en cola.

Ejemplo — Auto-completar detalles del usuario conectado:

Ferndesk('init', { widgetId: 'your-widget-id' });
Ferndesk('prefill', {
  name: user.fullName,
  email: user.email
});
Ferndesk('open');

Ejemplo — Pre-poblar informes de error:

// On crash page
Ferndesk('prefill', {
  subject: 'App Error',
  message: 'Error: ' + error.message
});
Ferndesk('open');

Advertencias de consola:

• Ferndesk: 'prefill' ignored because the widget has not been initialised — Llama primero a init().

Métodos de navegación de contenido

OpenArticle

Abre un artículo específico en el widget.

Ferndesk('openArticle', { shortId: 'help-123', presentation: 'widget' })

Parámetros:

• shortId (string, obligatorio): La última parte del ID del artículo.

• presentation (string, opcional): Cómo mostrar el artículo. Opciones: 'widget' (predeterminado), 'sidebar', 'modal', 'inline'.

• anchor (elemento HTML, opcional): Requerido para la presentación 'inline'. El elemento cerca del cual se anclará el artículo.

Retorna: Nada.

Modos de presentación:

• widget (predeterminado): El artículo se abre dentro del widget de ayuda principal.

• sidebar: El artículo se desliza desde el borde derecho como un panel lateral.

• modal: El artículo se abre en una superposición de pantalla completa centrada.

• inline: El artículo se expande cerca del elemento ancla (requiere el parámetro anchor).

Ejemplo — Abrir artículo en modal al hacer clic en un botón:

document.getElementById('faq-button').addEventListener('click', () => {
  Ferndesk('openArticle', { shortId: 'faq-pricing', presentation: 'modal' });
});

Ejemplo — Abrir artículo inline junto a un elemento:

const anchorElement = document.getElementById('billing-info');
Ferndesk('openArticle', {
  shortId: 'billing-faq',
  presentation: 'inline',
  anchor: anchorElement
});

Errores de consola:

• Ferndesk: openArticle requires a shortId — falta el shortId.

• Ferndesk: Inline floating article requires an anchor element — presentation: 'inline' pero no se proporcionó ancla.

• Ferndesk: openArticle ignored because the widget has not been initialised — aún no se ha llamado a init().

OpenCollection

Abre una colección específica en el widget.

Ferndesk('openCollection', { shortId: 'getting-started' })

Parámetros:

• shortId (string, obligatorio): El ID corto de la colección desde tu centro de ayuda.

Retorna: Nada.

Comportamiento: Abre la colección dentro del panel de ayuda del widget, mostrando todos los artículos de esa colección.

Ejemplo — Explorar artículos de solución de problemas:

Ferndesk('openCollection', { shortId: 'xFqsqw' });

Search

Puebla la búsqueda del widget y muestra los resultados.

Ferndesk('search', { query: 'billing issues' })

Parámetros:

• query (string, obligatorio): La consulta de búsqueda. No debe estar vacía.

Retorna: Nada.

Comportamiento: Abre el widget y muestra los resultados de búsqueda que coinciden con la consulta. Si no hay resultados que coincidan, muestra "No se encontraron resultados".

Ejemplo — Buscar cuando el usuario presiona una combinación de teclas:

document.addEventListener('keydown', (e) => {
  if (e.key === '?' && e.ctrlKey) {
    Ferndesk('search', { query: 'download videos' });
  }
});

Errores de consola:

• Ferndesk: search requires a non-empty query — el parámetro query está vacío o falta.

Atributos de datos para activadores integrados

Además de los métodos del SDK, puedes usar atributos de datos HTML para activar acciones del widget sin JavaScript:

data-ferndesk-article

Abre un artículo en modo widget al hacer clic.

<button data-ferndesk-article="help-123">Learn More</button>

Hacer clic en este botón abre el artículo con ID "help-123" en el panel principal del widget.

data-ferndesk-article-modal

Abre un artículo en modo modal al hacer clic.

<a href="#" data-ferndesk-article-modal="pricing-faq">View Pricing FAQs</a>

Hacer clic en este enlace abre el artículo en una superposición modal centrada.

data-ferndesk-article-sidebar

Abre un artículo en modo barra lateral al hacer clic.

<button data-ferndesk-article-sidebar="troubleshooting">Troubleshoot</button>

Hacer clic abre el artículo en una barra lateral deslizante.

data-ferndesk-article-inline

Abre un artículo en modo inline anclado al elemento clicado.

<button id="my-button" data-ferndesk-article-inline="quick-help">Quick Help</button>

Hacer clic en este botón abre el artículo de forma integrada cerca del botón. Si no se encuentra ningún ancla, la consola del navegador advierte y vuelve al modo modal.

Gestión de errores y registros

El SDK registra errores y advertencias en la consola del navegador (no se muestran a los usuarios finales). Los mensajes comunes incluyen:

Cumplimiento de la Política de Seguridad de Contenido (CSP)

Si tu sitio utiliza una Política de Seguridad de Contenido estricta, es posible que debas autorizar el dominio de Ferndesk:

Ejemplo de encabezado CSP:

script-src 'self' https://static.ferndesk.com;

Consideraciones de rendimiento

• Carga asíncrona: El script del SDK se carga de forma asíncrona en segundo plano. Tu página continúa cargándose mientras el SDK se inicializa.

• Aislamiento de Shadow DOM: El widget utiliza shadow DOM para encapsular estilos y evitar conflictos con el CSS de tu sitio.

• Carga diferida de contenido: Los artículos y resultados de búsqueda se cargan bajo demanda, no todos a la vez.

• Sin impacto en el rendimiento: El SDK añade una sobrecarga mínima, normalmente menos de 50 KB de JavaScript.

Ejemplos

Configuración básica

<html>
  <body>
    <!-- Your page content -->
    
    <script src="https://static.ferndesk.com/dist/sdk.js"></script>
    <script>
      Ferndesk('init', { widgetId: 'your-widget-id' });
    </script>
  </body>
</html>

Abrir artículo al hacer clic en un botón

<button id="help-btn">Get Help</button>

<script>
Ferndesk('init', { widgetId: 'your-widget-id' });

document.getElementById('help-btn').addEventListener('click', () => {
  Ferndesk('openArticle', {
    shortId: 'faq-overview',
    presentation: 'modal'
  });
});
</script>

Buscar al ingresar texto del usuario

<input id="search-input" type="text" placeholder="Search help..."/>

<script>
Ferndesk('init', { widgetId: 'your-widget-id' });

document.getElementById('search-input').addEventListener('keypress', (e) => {
  if (e.key === 'Enter') {
    Ferndesk('search', { query: e.target.value });
  }
});
</script>

Ayuda contextualizada en una aplicación React

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 (
    <div>
      {/* Your page content */}
    </div>
  );
}

Qué sigue

• Aprende cómo insertar el Widget de Autoservicio en tu sitio.

• Revisa la Información general del Widget de Autoservicio para detalles sobre las funciones.