Integra un asistente en una web

Publicarlo es básicamente copiar y pegar. Añades tres cosas a tu página —el script de ejecución de Seekdown, un elemento contenedor y un breve fragmento para iniciarlo— y listo. Este es el fragmento exacto que genera el producto por ti.

Antes de empezar

Añade el dominio del sitio a los orígenes permitidos.
Genera una clave de API si el modo de seguridad es API.
Ten a mano el ID del asistente.

Fragmento

<div id="seekdown-assistant-root"></div>

<!-- Include the public Seekdown runtime -->
<script src="https://saas.seekdown.ai/js/seekdown-assistant.js"></script>

<!-- Initialize the assistant with your assistantId and accessToken -->
<script>
  document.addEventListener('DOMContentLoaded', function () {
    if (window.skdwn?.startAssistant) {
      let seekdownAssistantOptions = {
        assistantId: 'your-assistant-id',
        accessToken: 'your-api-key-or-identity-access-token',
      };

      skdwn.startAssistant(seekdownAssistantOptions);
    } else {
      console.error('skdwn.startAssistant is not available.');
    }
  });
</script>

El token de acceso es opcional

Incluye accessToken solo cuando el modo de seguridad es API (una clave del asistente) u OIDC (el JWT de tu proveedor). Un asistente en modo None puede arrancar solo con assistantId.

Dónde colocar el fragmento

Pon el <script> de ejecución y el <div> contenedor justo antes de la etiqueta de cierre </body>, para que la página esté cargada antes de que arranque el asistente.
El contenedor <div id="seekdown-assistant-root"></div> debe existir en la página: el asistente se monta dentro de él.
Si tu web aplica una Content-Security-Policy estricta, permite el script y la conexión a saas.seekdown.ai, o el runtime no se cargará.

El fragmento de integración anotado: el script de ejecución, el contenedor seekdown-assistant-root y la llamada de inicialización.

Opciones de inicialización

startAssistant(options) recibe un objeto de opciones. Solo un par son obligatorias; el resto te permiten adaptar para quién es el asistente y qué aspecto tiene:

Opción	Obligatoria	Para qué sirve
`assistantId`	Sí	Qué asistente cargar.
`container`	No	Dónde montar el widget: un selector CSS o un elemento del DOM. Permite tener varios asistentes en una misma página, cada uno en su propio contenedor. Por defecto, el elemento con id `seekdown-assistant-root`. Consulta Varios asistentes en una misma página.
`accessToken`	En API / OIDC	La clave del asistente (modo API) o el JWT de tu proveedor (OIDC). Omítelo en un asistente en modo None.
`serviceURL`	Automática	La URL del servicio de Seekdown. Por defecto es `https://saas.seekdown.ai`, así que normalmente la omites.
`userId`	No	Una identidad estable para el visitante. Si no defines una, Seekdown genera un UUID y lo guarda en el navegador, de modo que un visitante que vuelve conserva su conversación y cuenta como un único usuario. Defínela para vincular al visitante con tu propio ID de cuenta.
`userInformation`	No	Un conjunto plano de pares clave–valor de texto sobre el visitante (p. ej., `email`, `plan`, `locale`). Viajan con la analítica como propiedades `user.*`, para que puedas segmentar el uso.
`additionalContext`	No	Un string de contexto adicional que se añade al prompt del asistente y que está disponible para sus plantillas en tiempo de ejecución; por ejemplo, una línea breve que describe al usuario que ha iniciado sesión o la página actual.
`config`	No	Sobrescrituras locales que se fusionan en profundidad con la configuración remota del asistente: tema, disposición, el botón flotante e incluso sobrescrituras de plantillas. Te permite integrar el mismo asistente con un aspecto distinto en webs distintas.
`baseURL`	No	URL base de los recursos estáticos del asistente; rara vez hace falta.
`isDebug`	No	Con `true`, registra el estado de las plantillas en la consola; útil mientras desarrollas sobrescrituras de plantillas.

Personaliza por visitante

userId, userInformation y additionalContext son la forma de que el asistente parezca conocer la cuenta del usuario; por ejemplo, pasa el plan del usuario que ha iniciado sesión para que las plantillas puedan saludarle o adaptar las respuestas, sin exponer nada secreto en la página.

Eventos del ciclo de vida

startAssistant(options, events?) acepta un segundo argumento opcional para que puedas engancharte a su ciclo de vida:

onStarted(): se dispara cuando el asistente se ha montado y (si está activado) ha restaurado la conversación anterior. Úsalo para ocultar un indicador de carga o registrar que el asistente está listo.
onError(error, info): se dispara si falla la inicialización; info.componentStack aporta contexto. Úsalo para mostrar una alternativa o reintentar.

<script>
  skdwn.startAssistant(
    {
      assistantId: 'your-assistant-id',
      accessToken: 'your-api-key',
      userId: 'customer-42',
      userInformation: { plan: 'pro', locale: 'en-US' },
      additionalContext: 'Signed-in user is on the Pro plan at Acme.',
      config: { settings: { baseTheme: 'dark' } },
    },
    {
      onStarted: function () { console.log('Assistant ready'); },
      onError: function (err, info) { console.error(err, info.componentStack); },
    }
  );
</script>

Varios asistentes en una misma página

Puedes ejecutar varios asistentes en la misma página a la vez; por ejemplo, una caja de búsqueda en la cabecera y un chat de soporte como botón flotante. La regla es sencilla: carga el runtime una vez, dale a cada asistente su propio contenedor y llama a startAssistant una vez por asistente con un container. Iniciar uno nunca desmonta los demás.

<!-- Load the runtime once -->
<script src="https://saas.seekdown.ai/js/seekdown-assistant.js"></script>

<!-- One container (with a unique id) per assistant -->
<div id="assistant-search"></div>
<div id="assistant-support"></div>

<script>
  const base = { accessToken: 'your-api-key', serviceURL: 'https://saas.seekdown.ai' };

  // Header search assistant
  skdwn.startAssistant({
    ...base,
    assistantId: 'as-search',
    container: '#assistant-search',
    config: { settings: { baseTemplate: 'overlay' } },
  });

  // Floating support chat
  skdwn.startAssistant({
    ...base,
    assistantId: 'as-support',
    container: '#assistant-support',
    config: { settings: { floatingActionButton: { useFloatingActionButton: true } } },
  });
</script>

Cada instancia está totalmente aislada —su propia conexión, configuración, plantillas y estado—, así que pueden compartir un assistantId o usar distintos sin interferir entre sí.

Dirigirse a un asistente concreto. El runtime expone una pequeña API en window.skdwn:

Propiedad / método	Devuelve
`skdwn.instances`	Un array con todos los asistentes activos de la página.
`skdwn.instance`	El asistente contextual: aquel cuya interfaz disparó el evento actual o que se está renderizando. Es a lo que se resuelven los manejadores de las plantillas (`onclick="skdwn.instance.helpers.…"`), así que cada widget siempre se controla a sí mismo.
`skdwn.instanceFor(target)`	El asistente montado en un contenedor dado (un selector o un elemento), o `undefined`. Úsalo para controlar un widget concreto desde el código de tu propia página.

// Open the support chat from your own button
const support = window.skdwn.instanceFor('#assistant-support');
window.skdwn.instance = support;                 // point the context at it
support.helpers.toggleShowFloatingWindow(true);  // helpers act on the current context

Algunas notas prácticas

- El <script> del runtime se carga una vez: expone el objeto único window.skdwn. - Los ids de los contenedores deben ser únicos; omite container para usar el #seekdown-assistant-root por defecto. - Los arranques se encolan (un contenedor no se puede montar dos veces a la vez), pero iniciar un segundo asistente no detiene el primero. - Reiniciar un asistente significa volver a llamar a startAssistant con el mismo container: solo se reinicia ese.

Comprueba el resultado

Abre la página y confirma que el asistente aparece y responde.

Solución de problemas

Si no aparece el widget, revisa la URL del script, el contenedor y la consola del navegador.
Si el acceso está bloqueado, revisa los orígenes permitidos y el token.