# 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 procéder. Aucun SDK, étape de build ou intégration à un 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 Accédez à votre site de documentation dans l’application GitBook, rendez-vous dans l’ **Paramètres** onglet puis dans **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 à l’intérieur de `` ou juste avant ``. ```html ``` {% endstep %} {% step %} #### Si votre documentation nécessite une authentification Si votre documentation [est derrière l’authentification](/docs/documentation/fr/acces-au-site/authenticated-access.md), le script doit inclure un jeton JWT signé. Ajoutez-le comme paramètre de requête : ```html ``` {% endstep %} {% step %} #### Vérifiez Rechargez votre page. Le widget devrait apparaître dans le coin inférieur droit. {% endstep %} {% endstepper %} ### Configurez l’intégration en option 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 `onglets`, 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 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 à 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 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 étapes ### Charger le script d’intégration de façon dynamique Si vous ne souhaitez charger le widget que conditionnellement, ou si vous devez attacher un jeton d’authentification à l’exécution, injectez le script par programmation. ```html ``` Utilisez ce modèle lorsque le widget doit se charger uniquement après une action de l’utilisateur ou selon 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 assistant ### Chat * `GitBook('postUserMessage', message: string)` - Envoyer un message au 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', {...})`: #### `onglets` Remplace les onglets affichés. La recherche est activée par défaut. Si vous définissez `onglets`, l’embed n’affiche que les onglets que vous avez सूचीés. * **Tapez**: `('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 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**: Ceci s’appelait auparavant `buttons`. Utilisez `actions` à la place. * **Tapez**: `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 * `libellé`: `string` - Texte du libellé du bouton * `onClick`: `() => void | Promise` - Fonction de rappel lors du clic #### `greeting` Message de bienvenue affiché dans l’onglet Assistant. * **Tapez**: `{ title: string, subtitle: string }` #### `assistantName` Remplace le nom de l’assistant affiché dans l’interface utilisateur. * **Tapez**: `string` * **Longueur max**: `32` caractères * **Exemple**: ```javascript window.GitBook('configure', { assistantName: 'Support Copilot' }); ``` #### `closeButton` Affiche un bouton de fermeture dans l’Assistant. * **Tapez**: `boolean` * **Exemple**: ```javascript window.GitBook('configure', { closeButton: true }); ``` #### `suggestions` Questions suggérées affichées dans l’écran de bienvenue de l’Assistant. * **Tapez**: `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’identité visuelle de l’Assistant. * **Tapez**: `boolean` * **Par défaut**: `true` * **Exemple**: ```javascript window.GitBook('configure', { trademark: false }); ``` #### `tools` Outils IA personnalisés pour étendre l’Assistant. Voir [Création d’outils personnalisés](/docs/documentation/fr/docs-site/embedding/configuration/creating-custom-tools.md) pour plus de détails. * **Tapez**: `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. * **Tapez**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }` * **Propriétés**: * `libellé`: `string` - Le texte affiché sur le bouton * `icon`: `'assistant' | 'sparkle' | 'help' | 'book'` - L’icône affichée sur le bouton * `assistant` - Icône d’assistant * `sparkle` - Icône d’étincelle * `help` - Icône d’aide / question * `book` - Icône de livre **Exemple :** ```javascript window.GitBook('configure', { button: { label: 'Demander', icon: 'assistant' } }); ``` {% hint style="info" %} **Remarque :** Cette option est disponible uniquement 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 se définissent sur le cadre plutôt que dans la configuration. Transmettez-les dans `frameOptions` lors de l’appel `GitBook('init', options, frameOptions)`. #### `colorScheme` Remplace le schéma de couleurs de l’intégration. Lorsqu’elle est omise, l’intégration suit le CSS de l’iframe `color-scheme` , ce qui lui permet d’hériter de la préférence de la page parente ou du navigateur. * **Tapez**: `'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 [Adaptive Content](/docs/documentation/fr/acces-au-site/adaptive-content.md) et [Accès authentifié](/docs/documentation/fr/acces-au-site/authenticated-access.md). * **Tapez**: `{ 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 votre documentation, et non l’exemple `docs.company.com`. * **Appel de GitBook avant le chargement du script** – Encapsulez les appels à l’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/docs-site/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 par défaut un z-index élevé. * **Oublier d’initialiser** – Assurez-vous d’appeler `GitBook('init', { siteURL: '...' })` avant d’utiliser les autres méthodes. --- # Agent Instructions: 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: ``` GET https://gitbook.com/docs/documentation/fr/docs-site/embedding/implementation/script.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.