Integra el widget en tu app

El widget se instala con una sola etiqueta de script, y todo lo demás en esta página parte de ahí: qué clave usar, cómo cargarlo en una single-page app, cómo montarlo en línea en lugar de flotante y qué debe permitir una Content-Security-Policy estricta.

Consigue tu clave de integración

El widget se autentica con una clave publicable. Las claves publicables pueden ir sin riesgo en el código de tu página: identifican tu espacio de trabajo pero no otorgan ninguna capacidad secreta.

1. 1
   Abre las claves de API en el panelVe a Configuración → Claves de API en el panel de tu espacio de trabajo.
2. 2
   Copia la clave publicableCopia la clave que empieza por pk_test_ para desarrollo o pk_live_ para producción — nunca una clave secreta gak_, que solo pertenece a tu servidor.
3. 3
   Haz coincidir la clave con el entornoEl widget deduce el entorno del prefijo de la clave; añade data-env solo cuando necesites forzarlo explícitamente.

La etiqueta de script

Pega la etiqueta justo antes del cierre de body en cada página donde deba aparecer el asistente. Debe conservar type="module": el widget es un módulo ES y no carga sin él.

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_test_..."
  data-position="bottom-right"
  data-env="development"
></script>

Eso es toda la instalación: el lanzador aparece en la esquina elegida y todo lo demás se diseña en el panel. La lista completa de atributos está en la referencia de configuración.

React, Vue y otras single-page apps

En una single-page app la instalación más simple sigue siendo la etiqueta estática en tu index.html: el widget sobrevive por sí solo a la navegación del lado del cliente. Si prefieres controlar el montaje desde tu árbol de componentes, inyecta el script en un efecto y desmóntalo en la limpieza:

import { useEffect } from 'react';

export function SyncanixWidget({ embedKey }: { embedKey: string }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.type = 'module';
    script.src = 'https://cdn.syncanix.com/widget.js';
    script.setAttribute('data-key', embedKey);
    document.body.appendChild(script);
    return () => {
      window.syncanix?.unmount();
      script.remove();
    };
  }, [embedKey]);
  return null;
}

El mismo patrón funciona en cualquier framework con hooks de montaje y limpieza: onMounted/onUnmounted en Vue, ngOnInit/ngOnDestroy en Angular, onMount en Svelte.

Montaje en línea en vez de flotante

Por defecto el widget flota como lanzador en una esquina de la página. Para colocar el chat dentro de tu propio diseño — un panel de ayuda, una barra lateral, una página completa — usa data-chat-size="embedded" y apunta data-mount-target a un selector CSS del contenedor que el widget debe llenar:

<div id="assistant-panel"></div>

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_live_..."
  data-chat-size="embedded"
  data-mount-target="#assistant-panel"
></script>

Envía la identidad de tu usuario

Sin identidad, el asistente trata a cada visitante como anónimo. Para que actúe como el usuario conectado, registra un proveedor de tokens: el widget lo llama antes de cada turno, así siempre se envía un token renovado. La configuración completa de cada modo de autenticación está en autenticar a tus usuarios.

window.syncanix?.setTokenProvider(async () => {
  // Called before each turn — return the signed-in user's current token.
  return auth.getTokenSilently();
});

Requisitos de Content-Security-Policy

Si tu sitio aplica una CSP estricta, permite estas tres cosas antes de integrar:

script-src  https://cdn.syncanix.com;
connect-src https://api.syncanix.com;
style-src   'unsafe-inline';

• script-src debe permitir cdn.syncanix.com — de donde se sirven widget.js y sus fragmentos diferidos.
• connect-src debe permitir api.syncanix.com — donde el widget transmite las conversaciones.
• style-src debe permitir 'unsafe-inline' — el widget inyecta sus estilos dentro de su propio Shadow DOM, así que nunca tocan ni leen los estilos de tu página.
• Las páginas que aplican Trusted Types funcionan sin cambios: el widget nunca alimenta un string sink.

Próximos pasos