Balise de script

Découvrez comment ajouter le widget Docs Embed à n’importe quel site web ou application web à l’aide d’une simple balise script

La méthode d’intégration la plus simple pour intégrer GitBook Assistant à votre site web ou à votre application est 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 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, puis allez à l’ Paramètres onglet puis à IA et 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 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://YOUR_DOCS_DOMAIN/~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 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.

Configurez l’intégration de manière facultative

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>
balise
  window.GitBook('configure', {
    button: {
      label: 'Ask',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    trademark: false,
    tabs: ['assistant', 'docs'],
    actions: [
      {
        icon: 'circle-question',
        label: 'Contacter le support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ],
    greeting: {
      title: 'Bienvenue',
      subtitle: 'Comment puis-je vous aider ?'
    },
    suggestions: [
      'Qu’est-ce que GitBook ?',
      'Comment puis-je commencer ?'
    ]
  });

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

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
Les suggestions affichées aux utilisateurs.

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

balise
  // 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 entre ouvert et fermé
  window.GitBook('toggle');
</script>

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

Naviguer et interagir par programmation

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

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

  // Passer à l’onglet assistant
  window.GitBook('navigateToAssistant');

  // Envoyer un message utilisateur à l’assistant
  window.GitBook('postUserMessage', 'Comment puis-je commencer ?');

  // Effacer l’historique actuel du chat
  window.GitBook('clearChat');
</script>

Les utilisations courantes 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 dynamiquement

Si vous souhaitez charger le widget uniquement de manière conditionnelle, ou si vous devez ajouter un jeton d’authentification à l’exécution, injectez le script par programmation.

balise
  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://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 ne doit se charger qu’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?: {...} }) - 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 docs
GitBook('navigateToAssistant') - Aller à 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

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.

Tapez: ('assistant' | 'docs')[]
Options:
- ['assistant', 'docs'] - Afficher les deux onglets
- ['assistant'] - Afficher uniquement l’onglet assistant
- ['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: Cela s’appelait auparavant buttons. Utilisez actions .

Tapez: Array<{ icon: string, label: string, onClick: () => void }>
Propriétés:
- icon: string - Nom de l’icône. Tout icône FontAwesome est pris en charge
- label: string - Texte du libellé du bouton
- onClick: () => void | Promise<void> - Fonction de rappel au clic

`greeting`

Message de bienvenue affiché dans l’onglet Assistant.

Tapez: { title: string, subtitle: string }

`suggestions`

Questions suggérées affichées sur l’écran d’accueil de l’Assistant.

Tapez: 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 l’image de marque de l’Assistant.

Tapez: 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 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:
- 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 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.

`visitor` (Accès authentifié)

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

Tapez: { token?: string, unsignedClaims?: Record<string, unknown> }
Propriétés:
- token: string (facultatif) - Jeton JWT signé
- unsignedClaims: Record<string, unknown> (facultatif) - Réclamations 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 de script.
La documentation authentifiée n’est pas accessible – 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é du contenu de votre site autorise le chargement des scripts et des 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 par défaut un z-index élevé.
Oubli de l’initialisation – Assurez-vous d’appeler GitBook('init', { siteURL: '...' }) avant d’utiliser les autres méthodes.

Mis à jour il y a 1 mois

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

Bonne nuit

Balise de script

Commencer

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

Ajoutez le script à votre HTML

Si votre documentation nécessite une authentification

Vérifiez

Configurez l’intégration de manière facultative

Contrôler la visibilité du widget

Naviguer et interagir par programmation

Charger le script d’intégration dynamiquement

Référence de l’API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`tabs`

`actions`

`greeting`

`suggestions`

`trademark`

`tools`

`bouton`

`visitor` (Accès authentifié)

Pièges courants

Bonne nuit

hashtagCommencer

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

hashtagAjoutez le script à votre HTML

hashtagSi votre documentation nécessite une authentification

hashtagVérifiez

hashtagConfigurez l’intégration de manière facultative

hashtagContrôler la visibilité du widget

hashtagNaviguer et interagir par programmation

hashtagCharger le script d’intégration dynamiquement

hashtagRéférence de l’API

hashtagInitialisation

hashtagContrôle du widget

hashtagNavigation

hashtagChat

hashtagConfiguration

hashtagOptions de configuration

hashtagtabs

hashtagactions

hashtaggreeting

hashtagsuggestions

hashtagtrademark

hashtagtools

hashtagbouton

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érifiez

Configurez l’intégration de manière facultative

Contrôler la visibilité du widget

Naviguer et interagir par programmation

Charger le script d’intégration dynamiquement

Référence de l’API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`tabs`

`actions`

`greeting`

`suggestions`

`trademark`

`tools`

`bouton`

`visitor` (Accès authentifié)

Pièges courants