Cómo insertar el widget de autoservicio

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

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

Prerrequisitos

• Acceso de administrador al panel de Ferndesk.

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

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

Antes de comenzar

Puede insertar el widget en:

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

• Páginas específicas: Añada el script solo a ciertas páginas donde desee que la ayuda sea visible.

• Aplicaciones de página única (SPA): Añada el script una vez en su diseño principal; este persistirá durante la navegación por las páginas.

Generar su código de inserción

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

2. En la barra lateral izquierda, bajo Centro de Ayuda, haga clic en Widget.

3. Haga clic en el botón de instalación de su widget.

4. Haga clic en el botón Copy Embed Code para copiar el fragmento completo a su portapapeles.

Su código de inserción se verá así:

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

Insertar el widget en su sitio

Para un sitio web HTML estándar

1. Abra el archivo HTML principal de su sitio web (a menudo llamado index.html, un archivo de plantilla o un archivo de inclusión de encabezado/pie de página).

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

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

Para una aplicación React

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

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

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. Abra su archivo de aplicación principal (por ejemplo, main.js o App.vue).

2. En un hook de ciclo de vida o como un script global, cargue e inicialice 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ñada el código de inserción a su plantilla de diseño o documento.

2. Para Next.js, use el componente <Script> en su _document.js o 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' });
        }}
      />
    </>
  );
}

Solución de problemas de inserción

El botón del widget no aparece

• Verifique la ubicación del script: Asegúrese de que el script esté colocado en el cuerpo (body) o encabezado (head) del HTML, no anidado dentro de bloques condicionales que podrían impedir su ejecución.

• Verifique la consola del navegador: Abra las herramientas de desarrollador de su navegador (F12 o Cmd+Option+I) y busque mensajes de error en la pestaña Consola.

• Verifique las solicitudes de red: En la pestaña Red de las herramientas de desarrollador, verifique que el script del SDK se cargue desde https://static.ferndesk.com/dist/sdk.js. Si está bloqueado (se muestra en rojo), verifique su configuración de seguridad o firewall.

• Bloqueadores de anuncios: Algunos bloqueadores de anuncios pueden impedir que el script de Ferndesk se cargue. Intente desactivar las extensiones y recargar la página.

El widget se está cargando pero aparece en blanco

• Espere al contenido: En conexiones lentas, el widget puede mostrar un indicador de carga brevemente.

• Verifique el contenido del centro de ayuda: Asegúrese de tener al menos un artículo publicado en su centro de ayuda de Ferndesk. Una base de conocimientos vacía dará como resultado un widget en blanco.

El widget cargó pero el estilo se ve mal

• Borre la caché del navegador: Es posible que su navegador esté almacenando archivos antiguos del widget. Borre la caché y recargue (Ctrl+Shift+R en Windows, Cmd+Shift+R en Mac).

• Verifique conflictos de CSS: Asegúrese de que el CSS global de su sitio web no esté invalidando los estilos del widget. El widget utiliza Shadow DOM para el aislamiento, pero las reglas globales aún pueden afectarlo.

El script del widget está bloqueado por la Política de Seguridad de Contenido (CSP)

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

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

• Usar un nonce: Si usa nonces, el código de inserción incluye soporte para atributos nonce. Contacte al soporte de Ferndesk para configuraciones avanzadas de CSP.

Personalización avanzada a través del SDK

Una vez insertado, puede controlar el widget programáticamente utilizando el SDK de Ferndesk. Por ejemplo:

• Abrir programáticamente un artículo desde el clic de un botón.

• Ocultar o mostrar el widget basado en acciones del usuario.

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

Consulte la documentación del SDK de Ferndesk para obtener detalles completos de la API y ejemplos de código.

Qué sigue

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

• Explore el SDK de Ferndesk para añadir control programático.

• Consulte Uso de análisis del centro de ayuda para mejorar su contenido para realizar un seguimiento del uso del widget.