> 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 de script La façon la plus simple d’ajouter Docs Embed à votre site web ou 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 de framework n’est requis. Incluez simplement le script et le widget apparaît sur votre page. ## Commencer {% stepper %} {% step %} #### Copiez l’URL de votre script d’intégration Dans l’application GitBook, ouvrez votre site de documentation, puis accédez à **Paramètres** onglet puis à **IA et MCP** et copiez l’URL du script d’intégration. Vous pouvez aussi le créer manuellement : ``` https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js ``` Remplacez votre `YOUR_DOCS_DOMAIN` 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 votre documentation nécessite une authentification Si votre documentation [est protégée 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 dans le coin inférieur droit. {% endstep %} {% endstepper %} ### Configurez l’intégration de manière facultative 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 d’accueil * Le nom de l’assistant affiché dans l’interface * Le bouton de fermeture dans l’assistant * Les invites suggérées affichées aux utilisateurs. La recherche est activée par défaut. Si vous définissez `tabs`, listez chaque onglet que vous souhaitez conserver. ### Définissez le schéma de couleurs Par défaut, l’intégration suit le CSS de l’iframe `color-scheme`. Cela lui permet d’hériter automatiquement du thème de votre application ou de la préférence du navigateur. Si vous souhaitez imposer 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, telles que `colorScheme` ou `visitor`. ### Contrôler la visibilité du widget Vous pouvez contrôler la visibilité et l’état à l’exécution via l’API. ```html ``` C’est utile lorsque vous souhaitez connecter le widget à vos propres déclencheurs d’interface. ### Naviguez et interagissez par programmation 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 parcours ### Charger le script d’intégration de manière dynamique Si vous souhaitez charger le widget uniquement de façon conditionnelle, ou si vous devez joindre un jeton d’authentification à l’exécution, injectez le script par programmation. ```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' })` - Initialiser 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')` - Naviguer vers l’onglet de l’assistant ### Chat * `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')` - Supprimer complètement le widget de la page ## Options de configuration ### `GitBook('configure')` La plupart des options de configuration sont disponibles via `GitBook('configure', {...})`: #### `tabs` Remplacez 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 la documentation * `['docs']` - Afficher uniquement l’onglet de documentation #### `actions` Boutons d'action personnalisés affichés dans la barre latérale à côté des onglets. Chaque bouton d'action déclenche un rappel lorsqu'il est cliqué. **Remarque**: C'était auparavant appelé `boutons`. Utilisez `actions` à la place. * **Type**: `Array<{ icon: string, label: string, onClick: () => void }>` * **Propriétés**: * `icône`: `string` - Nom de l’icône. N’importe quelle [icône FontAwesome](https://fontawesome.com/search) est pris en charge * `libellé`: `string` - Texte du libellé du bouton * `onClick`: `() => void | Promise` - Fonction de rappel lors du clic #### `message d'accueil` Message de bienvenue affiché dans l'onglet Assistant. * **Type**: `{ title: string, subtitle: string }` #### `assistantName` Remplacez le nom de l'assistant affiché dans l'interface. * **Type**: `string` * **Longueur maximale**: `32` caractères * **Exemple**: ```javascript window.GitBook('configure', { assistantName: 'Support Copilot' }); ``` #### `closeButton` Affichez 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 d'accueil de l'Assistant. * **Type**: `string[]` #### `marque` Affichez ou masquez la marque GitBook dans l'interface d'intégration — y compris le pied de page de l'intégration Docs et la marque de l'Assistant. * **Type**: `booléen` * **Par défaut**: `vrai` * **Exemple**: ```javascript window.GitBook('configure', { trademark: false }); ``` #### `outils` Outils 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?: {...} }>` #### `bouton` Configurez 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**: * `libellé`: `string` - Le texte affiché sur le bouton * `icône`: `'assistant' | 'sparkle' | 'help' | 'book'` - L’icône affichée sur le bouton * `assistant` - Icône Assistant * `sparkle` - Icône scintillante * `help` - Icône d’aide / question * `book` - Icône livre **Exemple :** ```javascript window.GitBook('configure', { button: { label: 'Ask', icon: 'assistant' } }); ``` {% hint style="info" %} **Remarque :** Cette option est uniquement disponible lors de l’utilisation de l’implémentation avec la balise 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 sur le cadre plutôt que dans la configuration. Transmettez-les dans `frameOptions` lors de l’appel de `GitBook('init', options, frameOptions)`. #### `colorScheme` Remplacez le jeu de couleurs de l'intégration. Lorsqu'il est omis, l'intégration suit le CSS de l'iframe `color-scheme`, 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) - Claims non signés pour les expressions dynamiques ## Pièges courants * **L’URL du script est incorrecte** – Assurez-vous d’utiliser l’URL réelle de votre documentation, et non l’exemple `docs.company.com`. * **Appeler GitBook avant le chargement du script** – Encadrez les appels API dans `script.onload` ou placez-les après la balise script. * **Documentation authentifiée inaccessible** – Si votre documentation nécessite une connexion, vous devez fournir `visitor.token` lors de l’initialisation. Voir [Utilisation avec une documentation authentifiée](/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. * **Widget non 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. * **Oubli 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.