Balise script

Apprenez à 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 dans votre site web ou application est un script autonome que vous incluez dans votre HTML. Chaque site de docs GitBook fournit un script d'intégration prêt à l'emploi qui charge automatiquement le widget et le connecte à vos docs. Cette page vous explique comment faire cela.

Aucun SDK, étape de build ou intégration de framework n'est requis. 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 docs dans l'application GitBook, rendez-vous dans Paramètres onglet puis dans IA & MCP et copiez l'URL du script d'intégration.

Vous pouvez aussi le construire manuellement :

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

Remplacez votre YOUR_DOCS_DOMAIN par le domaine réel de votre site de docs.

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://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>window.GitBook('show');</script>

Si vos docs nécessitent une authentification

Si vos docs sont protégées par authentification, le script doit inclure un jeton JWT signé.

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

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

Vérifiez

Rechargez votre page.

Le widget devrait apparaître dans le coin inférieur droit.

Configurer éventuellement l'intégration

Vous pouvez personnaliser le widget avant de l'afficher. Appelez configure après avoir chargé le script et avant d'appeler window.GitBook('show').

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>
  window.GitBook('configure', {
    button: {
      label: 'Ask',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    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 :

Libellé et icône du bouton
Onglets visibles à l'intérieur du widget
Boutons d'action personnalisés
Titre et sous-titre de l'accueil
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');

  // Supprimer 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/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 docs 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é comprennent :

Ajouter un lien profond vers une page de docs depuis votre application
Préremplir une question
Réinitialiser la conversation entre les 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'auth au moment de l'exécution, injectez le script de manière programmatique.

<script>
  function loadGitBookEmbed() {
    var token = "" // Remplissez-le avec votre jeton JWT si votre site requiert une authentification
    var script = document.createElement('script');
    script.src = 'https://YOUR_DOCS_DOMAIN/~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 drapeaux de fonctionnalité

Référence API

Initialisation

GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - Initialiser le widget avec l'URL du site et l'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 docs
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`

Remplacer 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 uniquement l'onglet assistant
- ['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'on clique dessus.

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 lorsqu'on clique

`greeting`

Message de bienvenue affiché dans l'onglet Assistant.

Type: { title: string, subtitle: string }

`suggestions`

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

Type: string[]

`tools`

Outils 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`

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:
- 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) - Reclamations 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 que le script ne soit chargé – Enveloppez les appels API dans script.onload ou placez-les après la balise script.
Docs authentifiées non accessibles – Si vos docs exigent une connexion, vous devez fournir le visitor.token lors de l'initialisation. Voir Utilisation avec des docs authentifiées.
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.
Oubli d'initialisation – Assurez-vous d'appeler GitBook('init', { siteURL: '...' }) avant d'utiliser d'autres méthodes.

Mis à jour il y a 2 jours

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 vos docs nécessitent une authentification

Vérifiez

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`

`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 vos docs nécessitent une authentification

hashtagVérifiez

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

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 vos docs nécessitent une authentification

Vérifiez

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`

`tools`

`button`

`visitor` (Accès authentifié)

Pièges courants