Cómo incrustar el Widget de autoservicio

El Widget de autoservicio se incrusta 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 a tu 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 tu sitio web.

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

Antes de empezar

Puedes incrustar el widget en:

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

• Páginas específicas: Añade el script solo en determinadas páginas donde quieras que la ayuda sea visible.

• Aplicaciones de una sola página (SPA): Añade el script una sola vez en tu diseño principal; se mantiene entre navegaciones de página.

Genera tu código de incrustació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 el botón Instalar de tu widget.

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

Tu código de incrustació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>

Incrusta 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 todo el código de incrustación justo antes de la etiqueta </body>:

Para una aplicación React

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

2. En un hook de useEffect, añade el script de incrustació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. Abre el archivo principal de tu 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 incrustación a tu diseño o plantilla de documento.

2. Para Next.js, usa el componente <Script> en tu _document.js o en el 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 incrustació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 en el 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 (se muestra en rojo), revisa tus ajustes de seguridad o el firewall.

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

El widget se está cargando pero aparece en blanco

• Espera el contenido: En conexiones lentas, el widget puede mostrar 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 provoca que el widget aparezca en blanco.

El widget se cargó, pero el estilo no se ve 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 (Ctrl+Shift+R en Windows, Cmd+Shift+R en Mac).

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

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

• Añade a la lista de अनुमति de 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;

• Usa un nonce: Si usas nonces, el código de incrustación incluye compatibilidad con atributos nonce. Ponte en contacto con el soporte de Ferndesk para configuraciones avanzadas de CSP.

Personalización avanzada mediante SDK

Una vez incrustado, puedes controlar el widget de forma programática usando el SDK de Ferndesk. Por ejemplo:

• Abrir un artículo de forma programática desde un clic en un botón.

• Ocultar o mostrar el widget en función de las acciones del usuario.

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

• Suscríbete a eventos del widget, como quickLinkClick. Las suscripciones a eventos pueden encolarse antes de que se cargue el SDK y devuelven una función de cancelación de suscripción inmediatamente.

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

Qué sigue

• Revisa 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 Cómo usar Analytics del centro de ayuda para mejorar tu contenido para hacer un seguimiento del uso del widget.