Cómo insertar el widget de autoservicio

El widget de autoservicio se inserta en tu sitio web mediante un sencillo fragmento de script.

Una vez añadido a tu HTML, aparece como un botón flotante en todas las páginas donde se carga el script, lo que permite a los visitantes acceder al centro de ayuda al instante.

Requisitos previos

• Acceso de administrador al panel de Ferndesk.

• Acceso de administrador o desarrollador al HTML o código de tu sitio web.

• Al menos un artículo publicado en tu centro de ayuda (recomendado).

Antes de comenzar

Puedes insertar el widget en:

• Todas las páginas: añade el script en una plantilla compartida o en un archivo de encabezado (recomendado para el acceso global).

• Páginas específicas: añade el script solo a determinadas páginas en las que quieras mostrar la ayuda.

• Aplicaciones de una sola página (SPA): añade el script una vez en tu diseño principal; seguirá activo al navegar entre páginas.

Genera tu código de inserción

1. Inicia sesión en el panel de Ferndesk.

2. En la barra lateral izquierda, en Centro de ayuda, haz clic en Widget.

3. Haz clic en Instalar en la tarjeta del widget que quieras insertar. Cada widget tiene su propio código de inserción y su propio ID de widget.

4. Haz clic en el botón Copiar código de inserción para copiar el fragmento completo al portapapeles.

Tu código de inserción tendrá este aspecto:

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

Inserta el widget en tu sitio

Para un sitio web HTML estándar

1. Abre el archivo HTML principal de tu sitio web (a menudo llamado index.html, un archivo de plantilla o un include de encabezado/pie de página).

2. Busca la etiqueta de cierre </body> cerca del final del archivo.

3. Pega el código de inserción completo justo antes de la etiqueta </body>:

Para una aplicación React

1. Abre el diseño principal o el componente de la aplicación (por ejemplo, App.js o _app.js en Next.js).

2. En un hook useEffect, añade el script de inserción después de que se monte el componente:

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

Para una aplicación Vue

1. Abre el archivo principal de la aplicación (por ejemplo, main.js o App.vue).

2. En un hook del ciclo de vida o como script global, carga e inicializa el 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' });
      };
    });
  }
};

Para un generador de sitios estáticos (Next.js, Gatsby, etc.)

1. Añade el código de inserción a tu diseño o plantilla de documento.

2. En Next.js, usa el componente <Script> en tu _document.js o diseño:

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

Solución de problemas de inserción

El botón del widget no aparece

• Comprueba la ubicación del script: asegúrate de que el script esté colocado en el body o head del HTML y no anidado dentro de bloques condicionales que puedan impedir su ejecución.

• Comprueba la consola del navegador: abre las herramientas de desarrollo de tu navegador (F12 o Cmd+Option+I) y busca mensajes de error en la pestaña Console.

• Comprueba las solicitudes de red: en la pestaña Network de las herramientas de desarrollo, verifica que el script del SDK se cargue desde https://static.ferndesk.com/dist/sdk.js. Si está bloqueado (aparece en rojo), revisa la configuración de seguridad o el firewall.

• Bloqueadores de anuncios: algunos bloqueadores de anuncios pueden impedir que se cargue el script de Ferndesk. Intenta desactivar las extensiones y volver a cargar la página.

El widget se está cargando, pero aparece vacío

• Espera a que se cargue el contenido: con conexiones lentas, es posible que el widget muestre brevemente un indicador de carga.

• Comprueba el contenido del centro de ayuda: asegúrate de tener al menos un artículo publicado en tu centro de ayuda de Ferndesk. Una base de conocimientos vacía hace que el widget aparezca en blanco.

El widget se cargó, pero los estilos no se ven bien

• Borra la caché del navegador: es posible que tu navegador esté almacenando en caché archivos antiguos del widget. Borra la caché y vuelve a cargar la página (Ctrl+Shift+R en Windows, Cmd+Shift+R en Mac).

• Comprueba si hay conflictos de CSS: asegúrate de que el CSS global de tu sitio web no esté sobrescribiendo los estilos del widget. El widget utiliza shadow DOM para aislarse, pero las reglas globales aún pueden afectarlo.

El script del widget está bloqueado por la Content Security Policy (CSP)

• Añadir a la lista de permitidos de la CSP: añade https://static.ferndesk.com a la directiva script-src del encabezado CSP.

• Ejemplo de encabezado CSP: script-src 'self' https://static.ferndesk.com;

• Usar un nonce: si utilizas nonces, el código de inserción admite atributos nonce. Ponte en contacto con el soporte de Ferndesk para obtener información sobre configuraciones avanzadas de CSP.

Personalización avanzada mediante el SDK

Una vez insertado, puedes controlar el widget mediante programación usando el SDK de Ferndesk. Por ejemplo:

• Abrir un artículo mediante programación al hacer clic en un botón.

• Ocultar o mostrar el widget según las acciones del usuario.

• Activar una búsqueda desde la interfaz de usuario de tu sitio.

• Suscribirte a eventos del widget, como quickLinkClick. Las suscripciones a eventos se pueden poner en cola antes de que se cargue el SDK y devuelven inmediatamente una función para cancelar la suscripción.

Consulta la documentación del SDK de Ferndesk para obtener todos los detalles de la API y ejemplos de código.

Qué sigue

• Consulta la descripción general del widget de autoservicio para conocer todas las funciones disponibles.

• Explora el SDK de Ferndesk para añadir control mediante programación.

• Consulta Uso de las analíticas del centro de ayuda para mejorar tu contenido para hacer un seguimiento del uso del widget.