Balise script

Apprenez comment ajouter le widget Docs Embed à n'importe quel site ou application web en utilisant une seule balise script

La méthode d'intégration la plus simple pour intégrer GitBook Assistant à votre site ou application consiste en 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 le widget automatiquement et le connecte à votre documentation. Cette page vous explique comment faire.

Aucun SDK, étape de build ou intégration de framework n'est nécessaire. Il suffit d'inclure le script et le widget apparaît sur votre page.

Commencer

Copiez l'URL de votre script d'intégration

Accédez à votre site de documentation dans l'application GitBook, allez dans Paramètres onglet puis dans IA & MCP et copiez l'URL du script d'intégration.

Vous pouvez aussi le construire manuellement :

https://VOTRE_DOMAINE_DOCS/~gitbook/embed/script.js

Remplacez votre VOTRE_DOMAINE_DOCS par le domaine réel de votre site de documentation.

Ajoutez le script à votre HTML

Ajoutez la balise suivante dans le HTML de votre page. Placez-la à l'intérieur de <head> ou juste avant </body>.

<script src="https://VOTRE_DOMAINE_DOCS/~gitbook/embed/script.js"></script>
<script>window.GitBook('show');</script>

Si votre documentation nécessite une authentification

Si votre documentation est protégée par une authentification, le script doit inclure un jeton JWT signé.

Ajoutez-le en tant que paramètre de requête :

<script src="https://VOTRE_DOMAINE_DOCS/~gitbook/embed/script.js?jwt_token=VOTRE_TOKEN"></script>

Vérifier

Rechargez votre page.

Le widget devrait apparaître en bas à droite.

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').

<script src="https://VOTRE_DOMAINE_DOCS/~gitbook/embed/script.js"></script>
<script>
  window.GitBook('configure', {
    button: {
      label: 'Ask',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    trademark: false,
    tabs: ['assistant', 'docs'],
    actions: [
      {
        icon: 'circle-question',
        label: 'Contact support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ],
    greeting: {
      title: 'Welcome',
      subtitle: 'How can I help?'
    },
    suggestions: [
      'What is GitBook?',
      'How do I get started?'
    ]
  });

  window.GitBook('show');
</script>

En utilisant cette méthode, vous pouvez personnaliser :

Le libellé et l'icône du bouton
Les onglets visibles à l'intérieur du widget
Les boutons d'action personnalisés
Le titre et le sous-titre du message d'accueil
Les invites suggérées affichées aux utilisateurs.

Vous pouvez contrôler la visibilité et l'état à l'exécution via l'API.

<script>
  // Rendre le widget visible
  window.GitBook('show');

  // Retirer le widget de la page
  window.GitBook('hide');

  // Ouvrir le panneau du widget
  window.GitBook('open');

  // Fermer le panneau du widget
  window.GitBook('close');

  // Basculer ouvert ou fermé
  window.GitBook('toggle');
</script>

Ceci est utile lorsque vous souhaitez connecter le widget à vos propres déclencheurs d'interface utilisateur.

Naviguer et interagir programmatiquement

Vous pouvez piloter le widget depuis votre code pour naviguer, changer d'onglet ou envoyer des messages.

<script>
  // Ouvrir une page de documentation spécifique dans le widget
  window.GitBook('navigateToPage', '/getting-started');

  // Basculer vers l'onglet assistant
  window.GitBook('navigateToAssistant');

  // Envoyer un message utilisateur à l'assistant
  window.GitBook('postUserMessage', 'How do I get started?');

  // Effacer l'historique de discussion actuel
  window.GitBook('clearChat');
</script>

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 différents flux

Charger le script d'intégration dynamiquement

Si vous ne voulez charger le widget que conditionnellement, ou si vous devez attacher un jeton d'authentification à l'exécution, injectez le script programmatiquement.

<script>
  function loadGitBookEmbed() {
    var token = "" // Remplissez-le avec votre jeton JWT si votre site nécessite une authentification
    var script = document.createElement('script');
    script.src = 'https://VOTRE_DOMAINE_DOCS/~gitbook/embed/script.js'
      + token ? '?jwt_token=' + encodeURIComponent(token) : ';
    script.async = true;
    script.onload = function () {
      window.GitBook('show');
    };
    document.head.appendChild(script);
  }

  loadGitBookEmbed();
</script>

Utilisez ce modèle lorsque le widget doit se charger uniquement après une action utilisateur ou des indicateurs de fonctionnalité

Référence API

Initialisation

GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - Initialiser le widget avec l'URL du site et un accès authentifié optionnel

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

GitBook('navigateToPage', path: string) - Naviguer vers une page spécifique dans l'onglet documentation
GitBook('navigateToAssistant') - Naviguer vers l'onglet assistant

Chat

GitBook('postUserMessage', message: string) - Poster 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

Les options de configuration sont disponibles via GitBook('configure', {...}):

`tabs`

Remplacez les onglets affichés. Par défaut, la configuration de votre site est utilisée.

Type: ('assistant' | 'docs')[]
Options:
- ['assistant', 'docs'] - Afficher les deux onglets
- ['assistant'] - Afficher seulement l'onglet assistant
- ['docs'] - Afficher seulement l'onglet documentation

`actions`

Boutons d'action personnalisés rendus dans la barre latérale aux côtés des onglets. Chaque bouton d'action déclenche un rappel lorsqu'il est cliqué.

Remarque: Ceci s'appelait auparavant 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 est prise en charge
- label: string - Texte du libellé du bouton
- onClick: () => void | Promise<void> - Fonction de rappel lors du clic

`greeting`

Message de bienvenue affiché dans l'onglet Assistant.

Type: { title: string, subtitle: string }

`suggestions`

Questions suggérées affichées dans l'écran d'accueil de l'Assistant.

Type: string[]

`trademark`

Afficher ou masquer la marque GitBook dans l'interface intégrée — y compris le pied de page de l'intégration Docs et le branding de l'Assistant.

Type: boolean
Par défaut: true
Exemple:

window.GitBook('configure', {
  trademark: false
});

`tools`

Outils d'IA personnalisés pour étendre l'Assistant. Voir Création d'outils personnalisés pour les détails.

Type: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

`button`

Configurer 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 Aide/question
  - book - Icône Livre

Exemple :

window.GitBook('configure', {
  button: {
    label: 'Ask',
    icon: 'assistant'
  }
});

Remarque : Cette option n'est disponible que lors de l'utilisation de la 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.

`visitor` (Accès authentifié)

À passer lors de l'initialisation avec GitBook('init', options, frameOptions). Utilisé pour Contenu adaptatif et Accès authentifié.

Type: { token?: string, unsignedClaims?: Record<string, unknown> }
Propriétés:
- token: string (optionnel) - Jeton JWT signé
- unsignedClaims: Record<string, unknown> (optionnel) - Assertions 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, pas l'exemple docs.company.com.
Appeler GitBook avant que le script ne soit chargé – Enveloppez 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 le visitor.token lors de l'initialisation. Voir Utilisation avec une documentation authentifiée.
Erreurs CORS ou CSP – Assurez-vous que la politique de sécurité de contenu (Content Security Policy) 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.
Oublier d'initialiser – Assurez-vous d'appeler GitBook('init', { siteURL: '...' }) avant d'utiliser d'autres méthodes.

Mis à jour il y a 23 heures

Ce contenu vous a-t-il été utile ?

Bon après-midi

Balise script

Commencer

Copiez l'URL de votre script d'intégration

Ajoutez le script à votre HTML

Si votre documentation nécessite une authentification

Vérifier

Configurer éventuellement l'intégration

Contrôler la visibilité du widget

Naviguer et interagir programmatiquement

Charger le script d'intégration dynamiquement

Référence API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`tabs`

`actions`

`greeting`

`suggestions`

`trademark`

`tools`

`button`

`visitor` (Accès authentifié)

Pièges courants

Bon après-midi

hashtagCommencer

hashtagCopiez l'URL de votre script d'intégration

hashtagAjoutez le script à votre HTML

hashtagSi votre documentation nécessite une authentification

hashtagVérifier

hashtagConfigurer éventuellement l'intégration

hashtagContrôler la visibilité du widget

hashtagNaviguer et interagir programmatiquement

hashtagCharger le script d'intégration dynamiquement

hashtagRéférence API

hashtagInitialisation

hashtagContrôle du widget

hashtagNavigation

hashtagChat

hashtagConfiguration

hashtagOptions de configuration

hashtagtabs

hashtagactions

hashtaggreeting

hashtagsuggestions

hashtagtrademark

hashtagtools

hashtagbutton

hashtagvisitor (Accès authentifié)

hashtagPièges courants

Commencer

Copiez l'URL de votre script d'intégration

Ajoutez le script à votre HTML

Si votre documentation nécessite une authentification

Vérifier

Configurer éventuellement l'intégration

Contrôler la visibilité du widget

Naviguer et interagir programmatiquement

Charger le script d'intégration dynamiquement

Référence API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`tabs`

`actions`

`greeting`

`suggestions`

`trademark`

`tools`

`button`

`visitor` (Accès authentifié)

Pièges courants