Cómo incrustar el widget de autoservicio

El widget de autoservicio se incrusta en su sitio web mediante un simple 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, lo que permite a los visitantes acceder a su centro de ayuda al instante.

Requisitos previos

• Acceso de administrador al panel de Ferndesk.

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

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

Antes de empezar

Puede incrustar el widget en:

• Todas las páginas: Añada el script en una plantilla compartida o en un archivo de cabecera (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 una sola página (SPAs): Añada el script una vez en su diseño principal; este persistirá durante la navegación por las páginas.

Genere su código de inserción

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

2. En la barra lateral izquierda, bajo Help Center, 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 al 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>

Incruste el widget en su sitio

Para un sitio web HTML estándar

1. Abra el archivo HTML principal de su sitio (generalmente llamado index.html, un archivo de plantilla o un archivo de inclusión de cabecera/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 el 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 principal de la aplicación (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 diseño o plantilla de documento.

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

Resolució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 puedan impedir su ejecución.

• Revise la consola del navegador: Abra las herramientas para desarrolladores 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 para desarrolladores, verifique que el script SDK se cargue desde https://static.ferndesk.com/dist/sdk.js. Si está bloqueado (aparece en rojo), revise su configuración de seguridad o cortafuegos.

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

El widget se carga 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 resultará en un widget en blanco.

El widget se cargó pero el estilo no se ve bien

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

• Compruebe conflictos de CSS: Asegúrese de que el CSS global de su sitio web no esté anulando 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 cabecera CSP.

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

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

Personalización avanzada mediante SDK

Una vez incrustado, 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 Cómo usar las analíticas del centro de ayuda para mejorar su contenido para realizar un seguimiento del uso del widget.