> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/fr/publier/embedding/implementation/script.md). # Balise script Découvrez comment ajouter le widget Docs Embed à n’importe quel site web ou application web à l’aide d’une seule balise script La façon la plus simple d’ajouter Docs Embed à votre site web ou à votre application est d’utiliser un script autonome que vous incluez dans votre HTML. Chaque site de documentation GitBook fournit un script d’intégration prêt à l’emploi qui charge automatiquement le widget et le connecte à votre documentation. Cette page vous explique comment faire. Aucun SDK, étape de build ou intégration à un framework n’est requis. Il suffit d’inclure le script et le widget apparaît sur votre page. ## Commencer {% stepper %} {% step %} #### Copiez l’URL de votre script d’intégration Rendez-vous sur votre site de documentation dans l’application GitBook, allez dans l’onglet **Paramètres** puis dans **IA & MCP** et copiez l’URL du script d’intégration. Vous pouvez aussi le créer manuellement : ``` https://VOTRE_DOMAINE_DOCS/~gitbook/embed/script.js ``` Remplacez votre `VOTRE_DOMAINE_DOCS` par le domaine réel de votre site de documentation. {% endstep %} {% step %} #### Ajoutez le script à votre HTML Ajoutez la balise suivante dans le HTML de votre page. Placez-la dans `` ou juste avant ``. ```html ``` {% endstep %} {% step %} #### Si vos documents nécessitent une authentification Si vos documents [sont protégés par authentification](/docs/documentation/fr/publier/site-audience/authenticated-access.md), le script doit inclure un jeton JWT signé. Ajoutez-le en tant que paramètre de requête : ```html ``` {% endstep %} {% step %} #### Vérifier Rechargez votre page. Le widget devrait apparaître en bas à droite. {% endstep %} {% endstepper %} ### Configurer éventuellement l’intégration Vous pouvez personnaliser le widget avant de l’afficher. Appelez `configure` après le chargement du script et avant d’appeler `window.GitBook('show')`. ```html ``` Avec cette méthode, vous pouvez personnaliser : * Le libellé et l’icône du bouton * Les onglets visibles dans le widget * Les boutons d’action personnalisés * Le titre et le sous-titre de bienvenue * Le nom de l’assistant affiché dans l’interface * Le bouton de fermeture dans l’Assistant * Les suggestions affichées aux utilisateurs. La recherche est activée par défaut. Si vous définissez `tabs`, répertoriez chaque onglet que vous souhaitez conserver. ### Définir le jeu de couleurs Par défaut, l’intégration suit la `color-scheme`CSS de l’iframe. Cela lui permet d’hériter automatiquement du thème de votre application ou de la préférence du navigateur. Si vous souhaitez forcer un mode, initialisez l’intégration et transmettez `colorScheme` dans `frameOptions`: ```html ``` Utilisez ce modèle lorsque vous avez besoin d’options au niveau du cadre, comme `colorScheme` ou `visitor`. ### Contrôler la visibilité du widget Vous pouvez contrôler la visibilité et l’état au moment de l’exécution via l’API. ```html ``` C’est utile lorsque vous souhaitez connecter le widget à vos propres déclencheurs d’interface. ### Naviguer et interagir par programme Vous pouvez piloter le widget depuis votre code pour naviguer, changer d’onglet ou envoyer des messages. ```html ``` Les utilisations typiques de cette fonctionnalité incluent : * Ajouter un lien profond vers une page de documentation depuis votre application * Préremplir une question * Réinitialiser la conversation entre les flux ### Charger le script d’intégration dynamiquement Si vous souhaitez charger le widget uniquement de manière conditionnelle, ou si vous devez ajouter un jeton d’authentification au moment de l’exécution, injectez le script par programme. ```html ``` Utilisez ce modèle lorsque le widget ne doit se charger qu’après une action de l’utilisateur ou via des indicateurs de fonctionnalité ## Référence de l’API ### Initialisation * `GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...}, colorScheme?: 'light' | 'dark' })` - Initialise le widget avec l’URL du site et des options de cadre facultatives ### Contrôle du widget * `GitBook('show')` - Afficher le bouton du widget * `GitBook('hide')` - Masquer le bouton du widget * `GitBook('open')` - Ouvrir la fenêtre du widget * `GitBook('close')` - Fermer la fenêtre du widget * `GitBook('toggle')` - Basculer la fenêtre du widget ### Navigation * `GitBook('navigateToPage', path: string)` - Naviguer vers une page spécifique dans l’onglet docs * `GitBook('navigateToAssistant')` - Aller à l’onglet Assistant ### Conversation * `GitBook('postUserMessage', message: string)` - Publier un message dans le chat * `GitBook('clearChat')` - Effacer l’historique du chat ### Configuration * `GitBook('configure', settings: {...})` - Configurer les paramètres du widget (voir la section Configuration ci-dessous) * `GitBook('unload')` - Retirer complètement le widget de la page ## Options de configuration ### `GitBook('configure')` La plupart des options de configuration sont disponibles via `GitBook('configure', {...})`: #### `tabs` Remplace les onglets affichés. La recherche est activée par défaut. Si vous définissez `tabs`, l’intégration n’affiche que les onglets que vous listez. * **Type**: `('assistant' | 'search' | 'docs')[]` * **Options**: * `['assistant', 'search', 'docs']` - Afficher tous les onglets * `['search', 'docs']` - Afficher uniquement la recherche et les docs * `['docs']` - Afficher uniquement l’onglet docs #### `actions` Boutons d’action personnalisés rendus dans la barre latérale à côté des onglets. Chaque bouton d’action déclenche un rappel lorsqu’il est cliqué. **Remarque**: Ceci était auparavant nommé `buttons`. Utilisez `actions` à la place. * **Type**: `Array<{ icon: string, label: string, onClick: () => void }>` * **Propriétés**: * `icon`: `string` - Nom de l’icône. Toute icône [FontAwesome](https://fontawesome.com/search) est prise en charge * `label`: `string` - Texte du libellé du bouton * `onClick`: `() => void | Promise` - Fonction de rappel au clic #### `greeting` Message de bienvenue affiché dans l’onglet Assistant. * **Type**: `{ title: string, subtitle: string }` #### `assistantName` Remplace le nom de l’assistant affiché dans l’interface. * **Type**: `string` * **Longueur max**: `32` caractères * **Exemple**: ```javascript window.GitBook('configure', { assistantName: 'Copilote de support' }); ``` #### `closeButton` Afficher un bouton de fermeture dans l’Assistant. * **Type**: `booléen` * **Exemple**: ```javascript window.GitBook('configure', { closeButton: true }); ``` #### `suggestions` Questions suggérées affichées dans l’écran de bienvenue de l’Assistant. * **Type**: `string[]` #### `trademark` Afficher ou masquer la marque GitBook dans l’interface d’intégration — y compris le pied de page de Docs Embed et l’image de marque de l’Assistant. * **Type**: `booléen` * **Par défaut**: `true` * **Exemple**: ```javascript window.GitBook('configure', { trademark: false }); ``` #### `tools` Outils d’IA personnalisés pour étendre l’Assistant. Voir [Créer des outils personnalisés](/docs/documentation/fr/publier/embedding/configuration/creating-custom-tools.md) pour plus de détails. * **Type**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>` #### `button` Configure le bouton du widget qui lance l’intégration (script autonome uniquement). Cela vous permet de personnaliser le libellé et l’icône du bouton qui apparaît dans le coin inférieur droit de votre page. * **Type**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }` * **Propriétés**: * `label`: `string` - Le texte affiché sur le bouton * `icon`: `'assistant' | 'sparkle' | 'help' | 'book'` - L’icône affichée sur le bouton * `assistant` - Icône Assistant * `sparkle` - Icône étincelle * `help` - Icône d’aide/d’interrogation * `book` - Icône Livre **Exemple :** ```javascript window.GitBook('configure', { button: { label: 'Demander', icon: 'assistant' } }); ``` {% hint style="info" %} **Remarque :** Cette option n’est disponible que lorsque vous utilisez l’implémentation par balise de script autonome. Pour les implémentations React ou Node.js, vous devrez créer votre propre bouton pour déclencher l’intégration. {% endhint %} ### `frameOptions` Certaines options sont définies au niveau du cadre plutôt qu’en configuration. Transmettez-les dans `frameOptions` lors de l’appel de `GitBook('init', options, frameOptions)`. #### `colorScheme` Remplace le jeu de couleurs de l’intégration. Lorsqu’elle est omise, l’intégration suit la `color-scheme`CSS de l’iframe, ce qui lui permet d’hériter de la page parente ou de la préférence du navigateur. * **Type**: `'light' | 'dark'` * **Exemple**: ```javascript window.GitBook( 'init', { siteURL: 'https://docs.company.com' }, { colorScheme: 'dark' } ); ``` #### `visitor` (Accès authentifié) À transmettre lors de l’initialisation avec `GitBook('init', options, frameOptions)`. Utilisé pour [Contenu adaptatif](/docs/documentation/fr/publier/adaptive-content.md) et [Accès authentifié](/docs/documentation/fr/publier/site-audience/authenticated-access.md). * **Type**: `{ token?: string, unsignedClaims?: Record }` * **Propriétés**: * `token`: `string` (facultatif) - Jeton JWT signé * `unsignedClaims`: `Record` (facultatif) - Revendications non signées pour les expressions dynamiques ## Pièges courants * **L’URL du script est incorrecte** – Assurez-vous d’utiliser l’URL réelle de vos docs, et non l’exemple `docs.company.com`. * **Appeler GitBook avant le chargement du script** – Enveloppez les appels API dans `script.onload` ou placez-les après la balise du script. * **Documents authentifiés inaccessibles** – Si vos documents nécessitent une connexion, vous devez fournir `visitor.token` lors de l’initialisation. Voir [Utilisation avec des documents authentifiés](/docs/documentation/fr/publier/embedding/using-with-authenticated-docs.md). * **Erreurs CORS ou CSP** – Assurez-vous que la politique de sécurité du contenu de votre site autorise le chargement de scripts et d’iframes depuis votre domaine GitBook. * **Le widget n’est pas visible** – Vérifiez les conflits de z-index avec d’autres éléments de votre page. Le widget utilise un z-index élevé par défaut. * **Oublier d’initialiser** – Assurez-vous d’appeler `GitBook('init', { siteURL: '...' })` avant d’utiliser les autres méthodes. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://gitbook.com/docs/documentation/fr/publier/embedding/implementation/script.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.