Configuración del widget
Configura el widget con atributos data-* en la etiqueta de script.
El widget se configura con atributos data-* en la etiqueta del script. Abajo está todo lo que el widget lee de esa etiqueta, agrupado por su función: los ajustes básicos, los avanzados y los atributos que activan un comportamiento completo.
<script
type="module"
src="https://cdn.syncanix.com/widget.js"
data-key="pk_test_..."
data-position="bottom-left"
data-env="development"
data-chat-size="large"
data-locale="fr"
data-config-load="eager"
></script>Atributos principales
- data-key — tu clave publicable (pk_test_… o pk_live_…). Obligatorio.
- data-enabled — establece false para cargar el script pero no montar el widget (true por defecto).
- data-position — esquina del lanzador: bottom-right (por defecto), bottom-left, top-right o top-left.
- data-locale — fija el idioma y la dirección de esta página (por ejemplo ar o en-US). Si lo omites, el widget sigue automáticamente el idioma de tu página.
- data-chat-size — small (por defecto), medium, large, fullscreen o embedded.
- data-env — development o production (si no, se infiere del prefijo de la clave).
- data-theme — una cadena JSON con anulaciones de tokens de tema.
El widget sigue el idioma de tu página por sí solo: no hace falta ningún atributo. Lee tu <html lang> y, cuando tu página muestra una escritura distinta de la que declara, se fía de lo que aparece en pantalla. Usa tu propio selector de idioma y el chat lo sigue, en el cliente, sin recargar y sin perder la conversación. Usa data-locale solo si quieres anularlo en una página concreta.
El primer mensaje de tu visitante fija el idioma de la conversación, y ahí se queda aunque después cambie el idioma de tu sitio: una conversación iniciada en hebreo sigue respondiendo en hebreo. Las etiquetas del widget y el aviso de IA siguen a tu página, de modo que el aviso siempre se lee en el idioma en el que está navegando. Si quiere cambiar de idioma, basta con que lo pida en el chat.
Atributos avanzados
- data-origin — el origen de la API de Syncanix (por defecto, la API de producción).
- data-theme-name — selecciona un diseño con nombre de tu biblioteca; auto sigue el ajuste claro/oscuro del sitio.
- data-prompt-profile — ejecuta en esta página un perfil de prompt concreto, por el nombre con el que lo publicaste. Solo pueden nombrarse los perfiles publicados; cualquier otro valor recurre a tu perfil activo.
- data-mount-target — un selector CSS para dónde montar un widget incrustado.
- data-api-base-url — dónde vive tu propia API, si está en un host distinto al de la página. Sin él, las acciones se envían al host de la propia página, lo que es correcto en un sitio de un solo host y erróneo en la habitual separación app./api.
- data-api-origins — una lista separada por comas de orígenes adicionales que también son tu API. Solo se observa el tráfico a tus propios orígenes, así que una API en un host aparte debe indicarse aquí o se ignora deliberadamente.
- data-theme-vars — asigna los roles de color del widget a tus propios nombres de variables CSS, en JSON. Se resuelve en vivo, así que sigue tu cambio claro/oscuro por sí solo; combínalo con data-theme-source para indicar el elemento donde se declaran tus variables.
- data-config-load — lazy (cargar los ajustes al abrir por primera vez, por defecto) o eager (al montar).
- data-executor — el nombre de una función global que ejecuta acciones del navegador o del host.
- data-token-provider — el nombre de una función global que devuelve el token del usuario final.
- data-step-up-provider — el nombre de una función global que activa la reautenticación reforzada.
- data-headers-provider — el nombre de una función global que devuelve encabezados de solicitud adicionales.
- data-client-witness — activa la observación pasiva del tráfico de la API, solo de su forma (desactivado por defecto).
- data-act-on-behalf-consent — exige un consentimiento único de «actuar en tu nombre» (desactivado por defecto).
Activar un comportamiento
Estos no configuran el aspecto del widget ni a dónde apunta: activan un comportamiento completo. Cada uno está desactivado salvo que lo añadas.
- data-trigger — un selector CSS para botones de tu propia página que deban abrir el chat. Un elemento de navegación, un enlace del pie, un botón de estado vacío. Al pulsar uno se alterna el panel, y el widget mantiene el estado expandido del botón anunciado correctamente a los lectores de pantalla.
- data-ask-about — permite que un visitante seleccione algo de tu página y pregunte al asistente sobre ello. Desactivado por defecto; además debe activarse para el espacio de trabajo.
- data-haptics — ponlo en false para que el widget no haga vibrar el teléfono cuando un visitante aprueba una acción. Activado por defecto, y siempre suprimido para quien tenga configurada la reducción de movimiento.
- data-frame-mode — cómo se comporta un widget dentro de un iframe: auto (por defecto), agent o standalone. Solo relevante si tu app incrusta partes de sí misma en frames.
- data-frame-origins — una lista separada por comas de orígenes exactos cuyas páginas enmarcadas puede manejar tu widget principal. Vacío o ausente significa ninguno, que es lo predeterminado.
- data-capture-closed-roots — ponlo en true si partes de tu página se construyen con una biblioteca de componentes de terceros en la que el asistente no puede mirar. Desactivado por defecto y solo útil cuando un control que debería poder operar le resulta invisible.
Mantener datos fuera del asistente
El asistente lee tu página para saber qué contiene. Estos tres deciden qué puede ver, para que un valor en pantalla nunca tenga que llegarle, y los formatos habituales de datos personales se retienen de forma predeterminada.
- data-block-selectors — una lista separada por comas de selectores CSS para las zonas que el asistente nunca debe ver. Un elemento que coincida, y todo lo que contiene, se excluye en el momento de la captura: ausente de forma demostrable, no eliminado después de leerlo. Marca el contenedor, no cada control.
- data-mask-selectors — una lista separada por comas de selectores CSS cuyos VALORES se ocultan mientras el campo sigue siendo visible. El asistente sabe que el campo existe, pero nunca lee lo que contiene: el mismo trato que reciben las contraseñas y las tarjetas de forma integrada.
- data-mask-pii — activado de forma predeterminada. Un valor que parece una dirección de correo, un número de la Seguridad Social de EE. UU. o un número de tarjeta se oculta aunque ningún selector lo nombre. Solo oculta el valor; el campo sigue visible. Ponlo en false únicamente donde aceptes que esos valores lleguen al asistente y a la transcripción guardada.