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 estarán 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.

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>

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 encontró.

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 caso 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 visible el botón del widget. Si ya es visible, no ocurre ningún cambio.

Ejemplo de caso 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 el panel de ayuda del widget mediante programación.

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 la página de inicio del centro de ayuda.

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

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

Close

Cierra el panel del widget que esté 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, borra 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 caso de uso: Limpiar el widget al descargar la página en aplicaciones de una sola página (SPA):

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

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 falló la verificación de la firma.

• Ferndesk: identify must be called from the same domain or 1-level subdomain — Se detectó una inconsistencia 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 se pongan en contacto contigo.

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 la obtención de ayuda rápidamente.

Parámetros: Objeto con campos de texto opcionales:

• name (string, opcional): Nombre del usuario

• email (string, opcional): Dirección de 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 precompletado 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 se complete el init y los datos se pondrán en cola.

Ejemplo — Rellenar automáticamente los datos del usuario conectado:

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

Ejemplo — Precompletar 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 capa superpuesta a pantalla completa centrada.

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

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

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

Ejemplo — Abrir un 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 — se usó 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 de 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 resolución de problemas:

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

Search

Rellena 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 coincidencias, muestra "No se han encontrado 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 inline

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>

Al hacer clic en este botón se 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>

Al hacer clic en este enlace se abre el artículo en una capa 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>

Al hacer clic se 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>

Al hacer clic en este botón se abre el artículo de forma inline cerca del botón. Si no se encuentra un anclaje, la consola del navegador avisa y vuelve al modo modal.

Gestión de errores y registros

El SDK registra errores y advertencias en la consola del navegador (no visibles para 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 los estilos y evitar conflictos con el CSS de tu sitio.

• Larga de contenido diferida (Lazy loading): Los artículos y los 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>

Búsqueda al escribir el 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 contextual 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>
  );
}

Siguientes pasos

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

• Revisa la Descripción general del Widget de Autoservicio para ver los detalles de las funciones.