Cómo insertar el Self-Service Widget

El Self-Service Widget se inserta en su sitio web utilizando un sencillo fragmento de código (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 que los visitantes accedan a su centro de ayuda al instante.

Prerrequisitos

• Acceso de administrador al panel de Ferndesk.

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

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

Antes de empezar

Puede insertar el widget en:

• Todas las páginas: Añada el script en una plantilla compartida o 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 sola 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 Help Center, haga clic en Widget.

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

4. Haga clic en el botón Copy Embed Code para copiar el fragmento completo en 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 tipo 'include' para cabecera o 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 el componente de la 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 el archivo principal de su 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 plantilla de diseño o documento.

2. Para Next.js, utilice el componente <Script> en su archivo _document.js o de 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

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

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

• Revise las solicitudes de red: En la pestaña Network de las herramientas de desarrollo, 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 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 carga pero aparece en blanco

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

• 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 ha cargado pero el diseño parece incorrecto

• 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).

• Revise 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 cabecera CSP.

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

• Usar 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 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 al hacer clic en un botón.

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

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

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

Próximos pasos

• Revise la descripción general del Self-Service Widget 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 rastrear el uso del widget.