diff --git a/es.json b/es.json
index 35a2e624ae..3979e6ca33 100644
--- a/es.json
+++ b/es.json
@@ -214,6 +214,7 @@
"pages": [
"es/assistant/configure",
"es/assistant/customize",
+ "es/assistant/widget",
"es/assistant/skills",
"es/assistant/use"
]
diff --git a/es/assistant/widget-preview.mdx b/es/assistant/widget-preview.mdx
new file mode 100644
index 0000000000..a4f8a2de12
--- /dev/null
+++ b/es/assistant/widget-preview.mdx
@@ -0,0 +1,11 @@
+---
+title: "Widget preview"
+description: "Host page for the live preview in the assistant widget playground."
+keywords: ["assistant", "widget", "preview"]
+mode: "custom"
+noindex: true
+---
+
+import { AssistantWidgetPreviewHost } from "/snippets/assistant-widget-preview-host.jsx";
+
+
diff --git a/es/assistant/widget.mdx b/es/assistant/widget.mdx
new file mode 100644
index 0000000000..abff512d20
--- /dev/null
+++ b/es/assistant/widget.mdx
@@ -0,0 +1,292 @@
+---
+title: "Widget de Mintlify"
+sidebarTitle: "Widget"
+description: "Instala y configura el widget de Mintlify para incrustar el asistente de IA entrenado con tu contenido en cualquier sitio web o aplicación web."
+keywords: ["assistant", "chat", "embed"]
+mode: "wide"
+---
+
+import { AssistantWidgetPlayground } from "/snippets/assistant-widget-playground.jsx";
+
+export const WidgetCodeBlock = ({ children, ...props }) => (
+ {children}
+);
+
+El [asistente](/es/assistant) responde preguntas en tu sitio de Mintlify. Para incrustar la misma capacidad en otro sitio o aplicación web, usa el widget. Con el widget, puedes ofrecer a tus usuarios acceso a un chat de IA entrenado con tu contenido en el panel de tu producto, sitio de marketing, portal de soporte u otros lugares.
+
+Usa el paquete [`@mintlify/assistant-widget`](https://www.npmjs.com/package/@mintlify/assistant-widget) para añadir tu asistente de Mintlify a cualquier sitio web o aplicación web. El paquete alojado gestiona su propio activador y se renderiza dentro de un Shadow DOM cerrado, lo que evita que los estilos de tu aplicación afecten al widget.
+
+La única opción de navegador obligatoria es el ID público del widget. Gestiona el estado de activación, los orígenes permitidos, los adjuntos y la protección contra bots desde tu panel. Configura las preguntas iniciales específicas del embed y un correo electrónico de soporte en la configuración del navegador.
+
+
+ ## Requisitos previos
+
+
+- Un [plan Pro o Enterprise](https://mintlify.com/pricing?ref=assistant). El widget usa los mismos créditos que el asistente.
+
+
+ ## Activar el widget
+
+
+1. Ve a la página [Widget](https://app.mintlify.com/settings/deployment/widget) de tu despliegue.
+2. Activa el widget.
+3. Añade los orígenes permitidos donde vas a incrustar el widget.
+4. Copia el ID del widget.
+
+
+ ## Instalar y configurar
+
+
+Usa el playground para configurar la presentación, las opciones visuales y los hooks de observación de tu widget. El bloque de código de instalación se actualiza a medida que cambias cada opción.
+
+
+ Reemplaza `YOUR_WIDGET_ID` en el código generado por el ID del widget de la página [Widget](https://app.mintlify.com/settings/deployment/widget) de tu panel.
+
+
+Después de añadir el código generado a tu sitio, recarga la página. Confirma que aparece el activador y, luego, haz clic en él y envía una pregunta de prueba para verificar que el widget está conectado.
+
+
+
+
+ Los scripts de módulo se difieren y se ejecutan en el orden del documento. Mantén el cargador alojado antes del bloque de inicialización cuando instales el widget con HTML, o el widget no se montará.
+
+
+
+ ## Abrir en la inicialización
+
+
+Establece `defaultOpen` en `true` para abrir el widget inmediatamente después de su primer montaje:
+
+```js
+await window.MintlifyAssistant.init({
+ id: "YOUR_WIDGET_ID",
+ defaultOpen: true,
+});
+```
+
+`defaultOpen` es `false` por defecto y solo se aplica a la primera inicialización. Llamar a `init()` de nuevo con el mismo ID de widget y endpoint de API no vuelve a abrir un widget que un visitante haya cerrado. Usa `open()` y `close()` para controlarlo después de la inicialización.
+
+
+ ## Usar un activador personalizado
+
+
+Espera a `init()` antes de llamar a otros métodos. Mantén el activador integrado o abre la presentación configurada desde cualquier botón de tu aplicación.
+
+```js
+await window.MintlifyAssistant.init({
+ id: "YOUR_WIDGET_ID",
+ supportEmail: "hi@mintlify.com",
+ starterQuestions: [
+ "How do I get started with Mintlify?",
+ "How do I customize my docs?",
+ "How do I deploy my docs?",
+ ],
+});
+
+document.querySelector("#help-button").addEventListener("click", () => {
+ void window.MintlifyAssistant.open({
+ source: "help-button",
+ focus: true,
+ });
+});
+```
+
+Para abrir el widget y enviar inmediatamente una pregunta, llama a `ask()`:
+
+```js
+await window.MintlifyAssistant.ask("How do I authenticate?", {
+ source: "authentication-guide",
+ open: true,
+ focus: true,
+});
+```
+
+Los metadatos de eventos y las solicitudes incluyen el valor `source`, que te permite distinguir las interacciones integradas de tus puntos de entrada personalizados.
+
+
+ ## Actualizar un widget montado
+
+
+Usa `update()` para cambiar la apariencia, las etiquetas, el correo de soporte, las preguntas iniciales o los hooks sin borrar la conversación actual. Solo se cambian los campos proporcionados.
+
+```js
+await window.MintlifyAssistant.update({
+ appearance: {
+ theme: "dark",
+ accent: "#7c3aed",
+ },
+ labels: {
+ title: "Docs copilot",
+ trigger: "Ask docs",
+ },
+ supportEmail: "support@example.com",
+ starterQuestions: [
+ "How do I get started?",
+ "How do I manage my account?",
+ ],
+});
+```
+
+Pasa `null` para restaurar un campo o grupo a su valor por defecto, eliminar el correo de soporte o restaurar una lista vacía de preguntas iniciales:
+
+```js
+await window.MintlifyAssistant.update({
+ appearance: {
+ accent: null,
+ },
+ supportEmail: null,
+ starterQuestions: null,
+ hooks: null,
+});
+```
+
+Cambiar `identity` inicia una nueva conversación. Cambiar el ID del widget o el endpoint de la API requiere llamar a `destroy()` antes de un nuevo `init()`.
+
+Puedes proporcionar `supportEmail` y `starterQuestions` durante la inicialización y cambiarlos más tarde con `update()`. Estos valores se aplican al embed actual y no se heredan desde tu panel de Mintlify.
+
+
+ ## Referencia de configuración
+
+
+
+ ### `AssistantConfig`
+
+
+Pasa este objeto a `init()`.
+
+| Option | Type | Description |
+| ------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------- |
+| `id` | string | ID público del widget desde el panel de Mintlify. |
+| `endpoint` | string | Sobrescribe el endpoint alojado de la API del widget. |
+| `identity` | string | Token firmado de identidad del usuario final. Omítelo para visitantes anónimos. |
+| `nonce` | string | Nonce de CSP copiado a los recursos creados por el widget. |
+| `defaultOpen` | boolean | Abre el widget en su primera inicialización. El valor por defecto es `false`. |
+| `appearance` | [`AssistantAppearance`](#assistantappearance) | Sobrescrituras visuales y de presentación. |
+| `labels` | [`AssistantLabels`](#assistantlabels) | Sobrescrituras de texto orientado al cliente. |
+| `supportEmail` | string | Establece la dirección de soporte que se muestra en la barra de herramientas del widget para este embed. |
+| `starterQuestions` | string[] | Establece hasta **tres** sugerencias de estado vacío para este embed. |
+| `hooks` | [`AssistantHooks`](#assistanthooks) | Observadores de eventos y errores. |
+
+
+ ### `AssistantAppearance`
+
+
+| Option | Values | Description |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `variant` | `widget`, `modal`, `panel` | Controla si el asistente se abre como popover anclado, diálogo centrado o panel lateral adaptable. |
+| `theme` | `light`, `dark`, `system` | Establece el esquema de color del widget. El valor por defecto es `system`. |
+| `accent` | CSS color | Establece el color de los controles principales. |
+| `radius` | CSS border radius | Establece el radio del panel, como `18px`. |
+| `font` | CSS font family | Usa una fuente ya cargada por tu aplicación. Por defecto se incluye Inter. |
+| `side` | `top`, `bottom`, `left`, `right`, `inline-start`, `inline-end` | Coloca el activador integrado en un borde de la pantalla. |
+| `align` | `start`, `center`, `end` | Alinea el activador a lo largo del borde seleccionado. |
+| `dismissOnInteractOutside` | boolean | Controla si las interacciones de puntero o foco fuera del asistente lo cierran. |
+| `logo` | URL or `{ light, dark }` | Reemplaza la marca predeterminada de Mintlify. |
+| `zIndex` | number | Cambia el orden de apilado del host del widget. |
+
+No se admiten sobrescrituras arbitrarias de CSS ni de paleta neutra. El Shadow DOM cerrado protege tanto a tu aplicación como al widget de regresiones de estilos entre sitios.
+
+
+ ### `AssistantLabels`
+
+
+| Option | Values | Description |
+| ------------- | ----------------- | ------------------------------------------------------------------- |
+| `title` | string or `null` | Establece el encabezado del panel. El valor por defecto es `Assistant`. |
+| `trigger` | string or `null` | Establece el texto del widget compacto y del activador del panel. |
+| `placeholder` | string or `null` | Establece el marcador de posición del compositor y del activador modal. |
+| `disclaimer` | string, `false`, or `null` | Establece el aviso del estado vacío. Pasa `false` para ocultarlo. |
+| `suggestions` | string or `null` | Establece el encabezado sobre las preguntas iniciales. El valor por defecto es `Suggestions`. |
+
+
+ ### `AssistantHooks`
+
+
+```js
+hooks: {
+ event(event) {
+ console.log(event.type, event.actor, event.source);
+ },
+ error(error) {
+ console.error(error.code, error.retryable, error.status);
+ },
+}
+```
+
+El hook `event` recibe metadatos de ciclo de vida e interacción para `init`, `open`, `close`, `ask`, `update`, `reset`, `navigate` y `destroy`. Los eventos no incluyen el texto de la pregunta, la identidad, la sesión ni los tokens CAPTCHA.
+
+El hook `error` recibe un `code` estable, un booleano `retryable` y un `status` HTTP opcional. Las excepciones lanzadas por cualquiera de los hooks no interrumpen el widget.
+
+
+ ### `AssistantOpenOptions`
+
+
+Pasa este objeto opcional a `open()`.
+
+| Option | Type | Description |
+| -------- | ------- | -------------------------------------------------------------------- |
+| `source` | string | Atribución definida por el cliente incluida en eventos y solicitudes. |
+| `focus` | boolean | Enfoca el compositor después de abrir. El valor por defecto es `true`. |
+
+
+ ### `AssistantAskOptions`
+
+
+Pasa este objeto opcional después de la cadena de la pregunta en `ask()`.
+
+| Option | Type | Description |
+| -------- | ------- | -------------------------------------------------------------------- |
+| `source` | string | Atribución definida por el cliente incluida en eventos y solicitudes. |
+| `open` | boolean | Abre el panel antes de enviar. El valor por defecto es `true`. |
+| `focus` | boolean | Enfoca el compositor al abrir. El valor por defecto es `true`. |
+
+
+ ### `AssistantUpdate`
+
+
+Pasa este objeto a `update()`. Todos los campos son opcionales y `null` restaura su valor por defecto.
+
+| Option | Type | Description |
+| ------------------ | ------------------------------------------------------- | ----------------------------------------------------------------- |
+| `identity` | string or `null` | Cambia la identidad firmada e inicia una nueva conversación. |
+| `appearance` | [`AssistantAppearance`](#assistantappearance) or `null` | Aplica parches en profundidad a la configuración de apariencia. |
+| `labels` | [`AssistantLabels`](#assistantlabels) or `null` | Aplica parches en profundidad al texto orientado al cliente. |
+| `supportEmail` | string or `null` | Cambia la dirección de soporte. Pasa `null` para eliminarla. |
+| `starterQuestions` | string[] or `null` | Cambia hasta tres sugerencias. Pasa `null` para restaurar una lista vacía. |
+| `hooks` | [`AssistantHooks`](#assistanthooks) or `null` | Aplica parches en profundidad a los observadores de eventos y errores. |
+
+
+ ## API del navegador
+
+
+| Method | Parameter types | Description |
+| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `init(config)` | [`AssistantConfig`](#assistantconfig) | Carga y monta el widget. Es la promesa de disponibilidad para todos los demás métodos. |
+| `open(options)` | [`AssistantOpenOptions`](#assistantopenoptions) | Abre la presentación configurada. |
+| `close()` | — | Cierra el widget. |
+| `ask(question, options)` | string, [`AssistantAskOptions`](#assistantaskoptions) | Abre el widget si se solicita y envía una pregunta. |
+| `update(config)` | [`AssistantUpdate`](#assistantupdate) | Aplica parches en profundidad a la identidad mutable, apariencia, textos y observadores. |
+| `reset()` | — | Inicia una conversación nueva. |
+| `destroy()` | — | Elimina el widget y libera sus recursos del navegador. |
+
+Las capturas de conversación permanecen privadas al widget. Cada método se resuelve en `void`.
+
+
+ ## Content Security Policy
+
+
+Si tu sitio usa una Content Security Policy, permite los orígenes requeridos por las funciones habilitadas de tu widget:
+
+| Directive | Source | Required for |
+| -------------------------------------------- | ----------------------------------- | --------------------------- |
+| `script-src` | `https://cdn.jsdelivr.net` | Cargador y runtime del widget |
+| `connect-src` | `https://api.mintlify.com` | API del widget |
+| `style-src` | `https://cdn.jsdelivr.net` | Hoja de estilos del widget |
+| `font-src` | `https://cdn.jsdelivr.net` | Fuente Inter incluida opcional |
+| `script-src`, `connect-src`, and `frame-src` | `https://challenges.cloudflare.com` | Protección contra bots Turnstile |
+| `script-src` | `https://js.hcaptcha.com` | Protección contra bots hCaptcha |
+| `connect-src` and `frame-src` | `https://*.hcaptcha.com` | Protección contra bots hCaptcha |
+
+Una política `script-src` estricta debe autorizar tanto el cargador como el script de inicialización. Pasar `nonce` a `init()` lo propaga solo a los recursos que el widget crea después de la inicialización.
+
+
diff --git a/fr.json b/fr.json
index b3c1ad7d47..a754385cba 100644
--- a/fr.json
+++ b/fr.json
@@ -214,6 +214,7 @@
"pages": [
"fr/assistant/configure",
"fr/assistant/customize",
+ "fr/assistant/widget",
"fr/assistant/skills",
"fr/assistant/use"
]
diff --git a/fr/assistant/widget-preview.mdx b/fr/assistant/widget-preview.mdx
new file mode 100644
index 0000000000..a4f8a2de12
--- /dev/null
+++ b/fr/assistant/widget-preview.mdx
@@ -0,0 +1,11 @@
+---
+title: "Widget preview"
+description: "Host page for the live preview in the assistant widget playground."
+keywords: ["assistant", "widget", "preview"]
+mode: "custom"
+noindex: true
+---
+
+import { AssistantWidgetPreviewHost } from "/snippets/assistant-widget-preview-host.jsx";
+
+
diff --git a/fr/assistant/widget.mdx b/fr/assistant/widget.mdx
new file mode 100644
index 0000000000..66bbb3eaf4
--- /dev/null
+++ b/fr/assistant/widget.mdx
@@ -0,0 +1,292 @@
+---
+title: "Widget Mintlify"
+sidebarTitle: "Widget"
+description: "Installez et configurez le widget Mintlify pour intégrer l'assistant IA entraîné sur votre contenu dans n'importe quel site web ou application web."
+keywords: ["assistant", "chat", "embed"]
+mode: "wide"
+---
+
+import { AssistantWidgetPlayground } from "/snippets/assistant-widget-playground.jsx";
+
+export const WidgetCodeBlock = ({ children, ...props }) => (
+ {children}
+);
+
+L'[assistant](/fr/assistant) répond aux questions sur votre site Mintlify. Pour intégrer la même capacité sur un autre site ou application web, utilisez le widget. Grâce au widget, vous pouvez donner à vos utilisateurs l'accès à un chat IA entraîné sur votre contenu dans le tableau de bord de votre produit, votre site marketing, votre portail d'assistance ou ailleurs.
+
+Utilisez le package [`@mintlify/assistant-widget`](https://www.npmjs.com/package/@mintlify/assistant-widget) pour ajouter votre assistant Mintlify à n'importe quel site web ou application web. Le package hébergé possède son propre déclencheur et s'affiche dans un Shadow DOM fermé, ce qui empêche les styles de votre application d'affecter le widget.
+
+La seule option de navigateur requise est l'ID public du widget. Gérez l'état d'activation, les origines autorisées, les pièces jointes et la protection contre les bots dans votre tableau de bord. Définissez les questions d'introduction spécifiques à l'intégration et une adresse e-mail d'assistance dans la configuration du navigateur.
+
+
+ ## Prérequis
+
+
+- Un [plan Pro ou Enterprise](https://mintlify.com/pricing?ref=assistant). Le widget utilise les mêmes crédits que l'assistant.
+
+
+ ## Activer le widget
+
+
+1. Accédez à la page [Widget](https://app.mintlify.com/settings/deployment/widget) de votre déploiement.
+2. Activez le widget.
+3. Ajoutez les origines autorisées où vous intégrez le widget.
+4. Copiez l'ID du widget.
+
+
+ ## Installer et configurer
+
+
+Utilisez le playground pour configurer la présentation, les options visuelles et les hooks d'observation de votre widget. Le bloc de code d'installation se met à jour à mesure que vous modifiez chaque option.
+
+
+ Remplacez `YOUR_WIDGET_ID` dans le code généré par l'ID du widget de la page [Widget](https://app.mintlify.com/settings/deployment/widget) de votre tableau de bord.
+
+
+Après avoir ajouté le code généré à votre site, rechargez la page. Vérifiez que le déclencheur apparaît, puis cliquez dessus et envoyez une question de test pour confirmer que le widget est connecté.
+
+
+
+
+ Les scripts de module sont différés et exécutés dans l'ordre du document. Gardez le chargeur hébergé avant le bloc d'initialisation lorsque vous installez le widget en HTML, sinon le widget ne parvient pas à se monter.
+
+
+
+ ## Ouvrir lors de l'initialisation
+
+
+Définissez `defaultOpen` sur `true` pour ouvrir le widget immédiatement après son premier montage :
+
+```js
+await window.MintlifyAssistant.init({
+ id: "YOUR_WIDGET_ID",
+ defaultOpen: true,
+});
+```
+
+`defaultOpen` est par défaut à `false` et ne s'applique qu'à la première initialisation. Appeler à nouveau `init()` avec le même ID de widget et le même endpoint API ne rouvre pas un widget qu'un visiteur a fermé. Utilisez `open()` et `close()` pour le contrôler après l'initialisation.
+
+
+ ## Utiliser un déclencheur personnalisé
+
+
+Attendez `init()` avant d'appeler d'autres méthodes. Conservez le déclencheur intégré ou ouvrez la présentation configurée depuis n'importe quel bouton de votre application.
+
+```js
+await window.MintlifyAssistant.init({
+ id: "YOUR_WIDGET_ID",
+ supportEmail: "hi@mintlify.com",
+ starterQuestions: [
+ "How do I get started with Mintlify?",
+ "How do I customize my docs?",
+ "How do I deploy my docs?",
+ ],
+});
+
+document.querySelector("#help-button").addEventListener("click", () => {
+ void window.MintlifyAssistant.open({
+ source: "help-button",
+ focus: true,
+ });
+});
+```
+
+Pour ouvrir le widget et envoyer immédiatement une question, appelez `ask()` :
+
+```js
+await window.MintlifyAssistant.ask("How do I authenticate?", {
+ source: "authentication-guide",
+ open: true,
+ focus: true,
+});
+```
+
+Les métadonnées d'événement et les requêtes incluent la valeur `source`, ce qui vous permet de distinguer les interactions intégrées de vos points d'entrée personnalisés.
+
+
+ ## Mettre à jour un widget monté
+
+
+Utilisez `update()` pour modifier l'apparence, les libellés, l'e-mail d'assistance, les questions d'introduction ou les hooks sans effacer la conversation en cours. Seuls les champs fournis sont modifiés.
+
+```js
+await window.MintlifyAssistant.update({
+ appearance: {
+ theme: "dark",
+ accent: "#7c3aed",
+ },
+ labels: {
+ title: "Docs copilot",
+ trigger: "Ask docs",
+ },
+ supportEmail: "support@example.com",
+ starterQuestions: [
+ "How do I get started?",
+ "How do I manage my account?",
+ ],
+});
+```
+
+Passez `null` pour restaurer un champ ou un groupe à sa valeur par défaut, supprimer l'e-mail d'assistance ou restaurer une liste vide de questions d'introduction :
+
+```js
+await window.MintlifyAssistant.update({
+ appearance: {
+ accent: null,
+ },
+ supportEmail: null,
+ starterQuestions: null,
+ hooks: null,
+});
+```
+
+La modification de `identity` démarre une nouvelle conversation. La modification de l'ID du widget ou de l'endpoint API nécessite d'appeler `destroy()` avant un nouveau `init()`.
+
+Vous pouvez fournir `supportEmail` et `starterQuestions` lors de l'initialisation et les modifier ultérieurement avec `update()`. Ces valeurs s'appliquent à l'intégration en cours et ne sont pas héritées de votre tableau de bord Mintlify.
+
+
+ ## Référence de configuration
+
+
+
+ ### `AssistantConfig`
+
+
+Passez cet objet à `init()`.
+
+| Option | Type | Description |
+| ------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------- |
+| `id` | string | ID public du widget provenant du tableau de bord Mintlify. |
+| `endpoint` | string | Remplace l'endpoint API du widget hébergé. |
+| `identity` | string | Jeton d'identité signé de l'utilisateur final. Omettez-le pour les visiteurs anonymes. |
+| `nonce` | string | Nonce CSP copié dans les ressources créées par le widget. |
+| `defaultOpen` | boolean | Ouvre le widget lors de sa première initialisation. La valeur par défaut est `false`. |
+| `appearance` | [`AssistantAppearance`](#assistantappearance) | Substitutions visuelles et de présentation. |
+| `labels` | [`AssistantLabels`](#assistantlabels) | Substitutions du texte visible par le client. |
+| `supportEmail` | string | Définit l'adresse d'assistance affichée dans la barre d'outils du widget pour cette intégration. |
+| `starterQuestions` | string[] | Définit jusqu'à **trois** invites d'état vide pour cette intégration. |
+| `hooks` | [`AssistantHooks`](#assistanthooks) | Observateurs d'événements et d'erreurs. |
+
+
+ ### `AssistantAppearance`
+
+
+| Option | Values | Description |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `variant` | `widget`, `modal`, `panel` | Contrôle si l'assistant s'ouvre comme un popover ancré, une boîte de dialogue centrée ou un panneau latéral réactif. |
+| `theme` | `light`, `dark`, `system` | Définit le schéma de couleurs du widget. La valeur par défaut est `system`. |
+| `accent` | CSS color | Définit la couleur des contrôles principaux. |
+| `radius` | CSS border radius | Définit le rayon du panneau, par exemple `18px`. |
+| `font` | CSS font family | Utilise une police déjà chargée par votre application. Par défaut, Inter est intégrée. |
+| `side` | `top`, `bottom`, `left`, `right`, `inline-start`, `inline-end` | Positionne le déclencheur intégré sur un bord de l'écran. |
+| `align` | `start`, `center`, `end` | Aligne le déclencheur le long du bord sélectionné. |
+| `dismissOnInteractOutside` | boolean | Contrôle si les interactions du pointeur ou du focus à l'extérieur ferment l'assistant. |
+| `logo` | URL or `{ light, dark }` | Remplace la marque Mintlify par défaut. |
+| `zIndex` | number | Modifie l'ordre d'empilement de l'hôte du widget. |
+
+Les substitutions CSS arbitraires et les palettes neutres ne sont pas prises en charge. Le Shadow DOM fermé protège à la fois votre application et le widget des régressions de style entre sites.
+
+
+ ### `AssistantLabels`
+
+
+| Option | Values | Description |
+| ------------- | ----------------- | ------------------------------------------------------------------- |
+| `title` | string or `null` | Définit l'en-tête du panneau. La valeur par défaut est `Assistant`. |
+| `trigger` | string or `null` | Définit le texte compact du widget et du déclencheur du panneau. |
+| `placeholder` | string or `null` | Définit le placeholder du compositeur et du déclencheur modal. |
+| `disclaimer` | string, `false`, or `null` | Définit l'avis d'état vide. Passez `false` pour le masquer. |
+| `suggestions` | string or `null` | Définit le titre au-dessus des questions d'introduction. La valeur par défaut est `Suggestions`. |
+
+
+ ### `AssistantHooks`
+
+
+```js
+hooks: {
+ event(event) {
+ console.log(event.type, event.actor, event.source);
+ },
+ error(error) {
+ console.error(error.code, error.retryable, error.status);
+ },
+}
+```
+
+Le hook `event` reçoit les métadonnées de cycle de vie et d'interaction pour `init`, `open`, `close`, `ask`, `update`, `reset`, `navigate` et `destroy`. Les événements n'incluent pas le texte de la question, l'identité, la session ou les jetons CAPTCHA.
+
+Le hook `error` reçoit un `code` stable, un booléen `retryable` et un `status` HTTP facultatif. Les exceptions levées par l'un ou l'autre des hooks n'interrompent pas le widget.
+
+
+ ### `AssistantOpenOptions`
+
+
+Passez cet objet facultatif à `open()`.
+
+| Option | Type | Description |
+| -------- | ------- | -------------------------------------------------------------------- |
+| `source` | string | Attribution définie par le client incluse dans les événements et les requêtes. |
+| `focus` | boolean | Met le focus sur le compositeur après ouverture. La valeur par défaut est `true`. |
+
+
+ ### `AssistantAskOptions`
+
+
+Passez cet objet facultatif après la chaîne de question dans `ask()`.
+
+| Option | Type | Description |
+| -------- | ------- | -------------------------------------------------------------------- |
+| `source` | string | Attribution définie par le client incluse dans les événements et les requêtes. |
+| `open` | boolean | Ouvre le panneau avant d'envoyer. La valeur par défaut est `true`. |
+| `focus` | boolean | Met le focus sur le compositeur lors de l'ouverture. La valeur par défaut est `true`. |
+
+
+ ### `AssistantUpdate`
+
+
+Passez cet objet à `update()`. Chaque champ est facultatif, et `null` restaure sa valeur par défaut.
+
+| Option | Type | Description |
+| ------------------ | ------------------------------------------------------- | ----------------------------------------------------------------- |
+| `identity` | string or `null` | Change l'identité signée et démarre une nouvelle conversation. |
+| `appearance` | [`AssistantAppearance`](#assistantappearance) or `null` | Applique un patch profond aux paramètres d'apparence. |
+| `labels` | [`AssistantLabels`](#assistantlabels) or `null` | Applique un patch profond au texte visible par le client. |
+| `supportEmail` | string or `null` | Change l'adresse d'assistance. Passez `null` pour la supprimer. |
+| `starterQuestions` | string[] or `null` | Change jusqu'à trois invites. Passez `null` pour restaurer une liste vide. |
+| `hooks` | [`AssistantHooks`](#assistanthooks) or `null` | Applique un patch profond aux observateurs d'événements et d'erreurs. |
+
+
+ ## API du navigateur
+
+
+| Method | Parameter types | Description |
+| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `init(config)` | [`AssistantConfig`](#assistantconfig) | Charge et monte le widget. Il s'agit de la promesse de disponibilité pour toutes les autres méthodes. |
+| `open(options)` | [`AssistantOpenOptions`](#assistantopenoptions) | Ouvre la présentation configurée. |
+| `close()` | — | Ferme le widget. |
+| `ask(question, options)` | string, [`AssistantAskOptions`](#assistantaskoptions) | Ouvre le widget si demandé et envoie une question. |
+| `update(config)` | [`AssistantUpdate`](#assistantupdate) | Applique un patch profond aux paramètres modifiables d'identité, d'apparence, de texte et d'observateurs. |
+| `reset()` | — | Démarre une nouvelle conversation. |
+| `destroy()` | — | Supprime le widget et libère ses ressources navigateur. |
+
+Les instantanés de conversation restent privés au widget. Chaque méthode se résout en `void`.
+
+
+ ## Content Security Policy
+
+
+Si votre site utilise une Content Security Policy, autorisez les origines requises par les fonctionnalités de votre widget activées :
+
+| Directive | Source | Required for |
+| -------------------------------------------- | ----------------------------------- | --------------------------- |
+| `script-src` | `https://cdn.jsdelivr.net` | Chargeur et runtime du widget |
+| `connect-src` | `https://api.mintlify.com` | API du widget |
+| `style-src` | `https://cdn.jsdelivr.net` | Feuille de style du widget |
+| `font-src` | `https://cdn.jsdelivr.net` | Police Inter intégrée facultative |
+| `script-src`, `connect-src`, and `frame-src` | `https://challenges.cloudflare.com` | Protection anti-bot Turnstile |
+| `script-src` | `https://js.hcaptcha.com` | Protection anti-bot hCaptcha |
+| `connect-src` and `frame-src` | `https://*.hcaptcha.com` | Protection anti-bot hCaptcha |
+
+Une politique `script-src` stricte doit toujours autoriser à la fois le chargeur et le script d'initialisation. Passer `nonce` à `init()` ne le propage qu'aux ressources créées par le widget après l'initialisation.
+
+
diff --git a/zh.json b/zh.json
index 5966cc353a..58ea7d65ec 100644
--- a/zh.json
+++ b/zh.json
@@ -211,6 +211,7 @@
"pages": [
"zh/assistant/configure",
"zh/assistant/customize",
+ "zh/assistant/widget",
"zh/assistant/skills",
"zh/assistant/use"
]
diff --git a/zh/assistant/widget-preview.mdx b/zh/assistant/widget-preview.mdx
new file mode 100644
index 0000000000..a4f8a2de12
--- /dev/null
+++ b/zh/assistant/widget-preview.mdx
@@ -0,0 +1,11 @@
+---
+title: "Widget preview"
+description: "Host page for the live preview in the assistant widget playground."
+keywords: ["assistant", "widget", "preview"]
+mode: "custom"
+noindex: true
+---
+
+import { AssistantWidgetPreviewHost } from "/snippets/assistant-widget-preview-host.jsx";
+
+
diff --git a/zh/assistant/widget.mdx b/zh/assistant/widget.mdx
new file mode 100644
index 0000000000..59cc0d1fda
--- /dev/null
+++ b/zh/assistant/widget.mdx
@@ -0,0 +1,292 @@
+---
+title: "Mintlify 小组件"
+sidebarTitle: "小组件"
+description: "安装并配置 Mintlify 小组件,在任意网站或 Web 应用中嵌入基于你的内容训练的 AI 助手。"
+keywords: ["assistant", "chat", "embed"]
+mode: "wide"
+---
+
+import { AssistantWidgetPlayground } from "/snippets/assistant-widget-playground.jsx";
+
+export const WidgetCodeBlock = ({ children, ...props }) => (
+ {children}
+);
+
+[助手](/zh/assistant)可回答关于你 Mintlify 站点的问题。若要在其他站点或 Web 应用中嵌入相同能力,请使用小组件。借助小组件,你可以在产品仪表板、营销站点、支持门户或其他位置为用户提供基于你内容训练的 AI 聊天服务。
+
+使用 [`@mintlify/assistant-widget`](https://www.npmjs.com/package/@mintlify/assistant-widget) 包,可将 Mintlify 助手添加到任何网站或 Web 应用。该托管包自带触发器,并在封闭的 Shadow DOM 内渲染,可防止你的应用样式影响小组件。
+
+浏览器端唯一必需的选项是公共小组件 ID。启用状态、允许的来源、附件以及机器人防护均可在仪表板中管理。可在浏览器配置中设置针对该嵌入的起始问题和支持邮箱。
+
+
+ ## 前置条件
+
+
+- [Pro 或 Enterprise 套餐](https://mintlify.com/pricing?ref=assistant)。小组件与助手共用同一额度。
+
+
+ ## 启用小组件
+
+
+1. 前往你部署的 [Widget](https://app.mintlify.com/settings/deployment/widget) 页面。
+2. 启用小组件。
+3. 添加嵌入小组件的允许来源。
+4. 复制小组件 ID。
+
+
+ ## 安装与配置
+
+
+使用交互式面板配置小组件的展示方式、视觉选项和观察者钩子。每次更改选项时,安装代码块都会随之更新。
+
+
+ 请将生成代码中的 `YOUR_WIDGET_ID` 替换为你仪表板 [Widget](https://app.mintlify.com/settings/deployment/widget) 页面中的小组件 ID。
+
+
+将生成的代码添加到站点后,重新加载页面。确认触发器已显示,然后点击它并发送一个测试问题,以验证小组件是否已连接。
+
+
+
+
+ Module 脚本会延迟加载并按文档顺序执行。当你使用 HTML 安装小组件时,请将托管加载器保持在初始化代码块之前,否则小组件将无法挂载。
+
+
+
+ ## 初始化时自动打开
+
+
+将 `defaultOpen` 设为 `true`,可在首次挂载后立即打开小组件:
+
+```js
+await window.MintlifyAssistant.init({
+ id: "YOUR_WIDGET_ID",
+ defaultOpen: true,
+});
+```
+
+`defaultOpen` 默认为 `false`,且仅在首次初始化时生效。若访客关闭小组件后,再次以相同的小组件 ID 和 API 端点调用 `init()` 并不会重新打开它。初始化之后请使用 `open()` 和 `close()` 来控制它。
+
+
+ ## 使用自定义触发器
+
+
+在调用其他方法前请先等待 `init()` 完成。你可以保留内置触发器,也可以从应用中任意按钮打开已配置的展示形式。
+
+```js
+await window.MintlifyAssistant.init({
+ id: "YOUR_WIDGET_ID",
+ supportEmail: "hi@mintlify.com",
+ starterQuestions: [
+ "How do I get started with Mintlify?",
+ "How do I customize my docs?",
+ "How do I deploy my docs?",
+ ],
+});
+
+document.querySelector("#help-button").addEventListener("click", () => {
+ void window.MintlifyAssistant.open({
+ source: "help-button",
+ focus: true,
+ });
+});
+```
+
+若要打开小组件并立即发送问题,请调用 `ask()`:
+
+```js
+await window.MintlifyAssistant.ask("How do I authenticate?", {
+ source: "authentication-guide",
+ open: true,
+ focus: true,
+});
+```
+
+事件元数据和请求中会包含 `source` 值,便于你区分内置交互与自定义入口。
+
+
+ ## 更新已挂载的小组件
+
+
+使用 `update()` 可在不清除当前会话的情况下更改外观、文案、支持邮箱、起始问题或钩子。只有传入的字段会被更改。
+
+```js
+await window.MintlifyAssistant.update({
+ appearance: {
+ theme: "dark",
+ accent: "#7c3aed",
+ },
+ labels: {
+ title: "Docs copilot",
+ trigger: "Ask docs",
+ },
+ supportEmail: "support@example.com",
+ starterQuestions: [
+ "How do I get started?",
+ "How do I manage my account?",
+ ],
+});
+```
+
+传入 `null` 可将某个字段或分组恢复为默认值、移除支持邮箱,或将起始问题列表恢复为空:
+
+```js
+await window.MintlifyAssistant.update({
+ appearance: {
+ accent: null,
+ },
+ supportEmail: null,
+ starterQuestions: null,
+ hooks: null,
+});
+```
+
+更改 `identity` 会开启新的会话。更改小组件 ID 或 API 端点则需要先调用 `destroy()`,再执行新的 `init()`。
+
+你可以在初始化时提供 `supportEmail` 和 `starterQuestions`,也可以稍后通过 `update()` 更改。这些值仅作用于当前嵌入,不会继承自你的 Mintlify 仪表板。
+
+
+ ## 配置参考
+
+
+
+ ### `AssistantConfig`
+
+
+将该对象传入 `init()`。
+
+| Option | Type | Description |
+| ------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------- |
+| `id` | string | 来自 Mintlify 仪表板的公共小组件 ID。 |
+| `endpoint` | string | 覆盖托管的小组件 API 端点。 |
+| `identity` | string | 签名的终端用户身份令牌。匿名访客可省略。 |
+| `nonce` | string | 复制到小组件所创建资源上的 CSP nonce。 |
+| `defaultOpen` | boolean | 在首次初始化时打开小组件。默认为 `false`。 |
+| `appearance` | [`AssistantAppearance`](#assistantappearance) | 视觉和展示相关的覆盖设置。 |
+| `labels` | [`AssistantLabels`](#assistantlabels) | 面向客户的文案覆盖设置。 |
+| `supportEmail` | string | 设置该嵌入在小组件工具栏中显示的支持邮箱。 |
+| `starterQuestions` | string[] | 为该嵌入设置最多 **三** 条空状态提示。 |
+| `hooks` | [`AssistantHooks`](#assistanthooks) | 事件和错误观察者。 |
+
+
+ ### `AssistantAppearance`
+
+
+| Option | Values | Description |
+| -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `variant` | `widget`, `modal`, `panel` | 控制助手以锚定弹层、居中对话框还是响应式侧边面板的形式打开。 |
+| `theme` | `light`, `dark`, `system` | 设置小组件的配色方案。默认为 `system`。 |
+| `accent` | CSS color | 设置主要控件的颜色。 |
+| `radius` | CSS border radius | 设置面板圆角,例如 `18px`。 |
+| `font` | CSS font family | 使用你的应用已加载的字体。默认使用内置的 Inter。 |
+| `side` | `top`, `bottom`, `left`, `right`, `inline-start`, `inline-end` | 将内置触发器定位到屏幕边缘。 |
+| `align` | `start`, `center`, `end` | 让触发器沿所选边缘对齐。 |
+| `dismissOnInteractOutside` | boolean | 控制在助手外部的指针或焦点交互是否将其关闭。 |
+| `logo` | URL or `{ light, dark }` | 替换默认的 Mintlify 标识。 |
+| `zIndex` | number | 更改小组件宿主的堆叠顺序。 |
+
+不支持任意 CSS 和中性色板覆盖。封闭的 Shadow DOM 可同时保护你的应用与小组件,防止跨站样式回归。
+
+
+ ### `AssistantLabels`
+
+
+| Option | Values | Description |
+| ------------- | ----------------- | ------------------------------------------------------------------- |
+| `title` | string or `null` | 设置面板标题。默认为 `Assistant`。 |
+| `trigger` | string or `null` | 设置紧凑型小组件和面板触发器的文字。 |
+| `placeholder` | string or `null` | 设置输入框和模态触发器的占位提示。 |
+| `disclaimer` | string, `false`, or `null` | 设置空状态免责声明。传入 `false` 可将其隐藏。 |
+| `suggestions` | string or `null` | 设置起始问题上方的标题。默认为 `Suggestions`。 |
+
+
+ ### `AssistantHooks`
+
+
+```js
+hooks: {
+ event(event) {
+ console.log(event.type, event.actor, event.source);
+ },
+ error(error) {
+ console.error(error.code, error.retryable, error.status);
+ },
+}
+```
+
+`event` 钩子会接收 `init`、`open`、`close`、`ask`、`update`、`reset`、`navigate` 和 `destroy` 的生命周期与交互元数据。事件不包含问题文本、身份、会话或 CAPTCHA 令牌。
+
+`error` 钩子会接收稳定的 `code`、一个 `retryable` 布尔值以及可选的 HTTP `status`。任一钩子抛出的异常都不会中断小组件。
+
+
+ ### `AssistantOpenOptions`
+
+
+将该可选对象传入 `open()`。
+
+| Option | Type | Description |
+| -------- | ------- | -------------------------------------------------------------------- |
+| `source` | string | 由客户定义的归因信息,会包含在事件和请求中。 |
+| `focus` | boolean | 打开后聚焦输入框。默认为 `true`。 |
+
+
+ ### `AssistantAskOptions`
+
+
+将该可选对象作为问题字符串之后的参数传入 `ask()`。
+
+| Option | Type | Description |
+| -------- | ------- | -------------------------------------------------------------------- |
+| `source` | string | 由客户定义的归因信息,会包含在事件和请求中。 |
+| `open` | boolean | 在发送前打开面板。默认为 `true`。 |
+| `focus` | boolean | 打开时聚焦输入框。默认为 `true`。 |
+
+
+ ### `AssistantUpdate`
+
+
+将该对象传入 `update()`。所有字段均为可选,`null` 表示恢复默认值。
+
+| Option | Type | Description |
+| ------------------ | ------------------------------------------------------- | ----------------------------------------------------------------- |
+| `identity` | string or `null` | 更改签名身份并开启新的会话。 |
+| `appearance` | [`AssistantAppearance`](#assistantappearance) or `null` | 深度合并外观设置。 |
+| `labels` | [`AssistantLabels`](#assistantlabels) or `null` | 深度合并面向客户的文案。 |
+| `supportEmail` | string or `null` | 更改支持邮箱。传入 `null` 可移除。 |
+| `starterQuestions` | string[] or `null` | 更改最多三条提示。传入 `null` 可恢复为空列表。 |
+| `hooks` | [`AssistantHooks`](#assistanthooks) or `null` | 深度合并事件和错误观察者。 |
+
+
+ ## 浏览器 API
+
+
+| Method | Parameter types | Description |
+| ------------------------ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `init(config)` | [`AssistantConfig`](#assistantconfig) | 加载并挂载小组件。这是所有其他方法的就绪 Promise。 |
+| `open(options)` | [`AssistantOpenOptions`](#assistantopenoptions) | 打开已配置的展示形式。 |
+| `close()` | — | 关闭小组件。 |
+| `ask(question, options)` | string, [`AssistantAskOptions`](#assistantaskoptions) | 按需打开小组件并发送一个问题。 |
+| `update(config)` | [`AssistantUpdate`](#assistantupdate) | 深度合并可变的身份、外观、文案和观察者设置。 |
+| `reset()` | — | 开启一次全新的会话。 |
+| `destroy()` | — | 移除小组件并释放其浏览器资源。 |
+
+会话快照始终保留在小组件内部。每个方法都会 resolve 为 `void`。
+
+
+ ## 内容安全策略
+
+
+如果你的站点使用了内容安全策略(CSP),请为所启用的小组件功能允许以下来源:
+
+| Directive | Source | Required for |
+| -------------------------------------------- | ----------------------------------- | --------------------------- |
+| `script-src` | `https://cdn.jsdelivr.net` | 小组件加载器与运行时 |
+| `connect-src` | `https://api.mintlify.com` | 小组件 API |
+| `style-src` | `https://cdn.jsdelivr.net` | 小组件样式表 |
+| `font-src` | `https://cdn.jsdelivr.net` | 可选的内置 Inter 字体 |
+| `script-src`, `connect-src`, and `frame-src` | `https://challenges.cloudflare.com` | Turnstile 机器人防护 |
+| `script-src` | `https://js.hcaptcha.com` | hCaptcha 机器人防护 |
+| `connect-src` and `frame-src` | `https://*.hcaptcha.com` | hCaptcha 机器人防护 |
+
+即使采用严格的 `script-src` 策略,也必须同时授权加载器和初始化脚本。向 `init()` 传入 `nonce` 时,仅会将其传播到小组件在初始化之后创建的资源。
+
+