Docs Agents are coming — a new way to ideate, plan, and ship docs.
Join the waitlist
PricingLog inSign up

Balise script

Ajoutez Docs Embed à n’importe quel site web avec une simple balise script

La façon la plus rapide d'ajouter Docs Embed à votre site Web ou application est de l'ajouter via une balise de script "autonome". Chaque site de docs dans GitBook inclut un script prêt à l'emploi pour intégrer vos docs en tant que widget.

Étapes

1

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

Accédez à Paramètres → IA & MCP onglet et copiez l'URL du script, ou utilisez le script à https://docs.company.com/~gitbook/embed/script.js (remplacez docs.company.com par l'URL réelle de votre site de docs).

2

Ajoutez la balise script à votre HTML

Placez ce code dans votre HTML <head> ou avant la fermeture de </body> balise :

<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
<script>
  // Initialiser avec accès authentifié (optionnel)
  window.GitBook('init', 
    { siteURL: 'https://docs.company.com' },
    { visitor: { token: 'your-jwt-token' } }
  );
  window.GitBook('show');
</script>
3

Remplacez l'URL des docs

Mettez à jour docs.company.com par l'URL réelle de votre site de docs.

4

Testez le widget

Chargez votre page. Le widget intégré devrait apparaître dans le coin inférieur droit.

5

Configurer éventuellement l'intégration

Ajoutez des options de personnalisation avant d'appeler show():

<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
<script>
  window.GitBook('init', { siteURL: 'https://docs.company.com' });
  
  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>
6

Contrôler la visibilité du widget

Utilisez l'API pour afficher, masquer, ouvrir ou fermer l'intégration :

<script>
  // Afficher le widget
  window.GitBook("show");

  // Masquer le widget
  window.GitBook("hide");

  // Ouvrir la fenêtre d'intégration
  window.GitBook("open");

  // Fermer la fenêtre d'intégration
  window.GitBook("close");

  // Basculer la fenêtre d'intégration
  window.GitBook("toggle");
</script>
7

Naviguer et interagir par programmation

Utilisez l'API pour naviguer vers des pages, changer d'onglet ou envoyer des messages :

<script>
  // Naviguer vers une page spécifique dans l'onglet docs
  window.GitBook('navigateToPage', '/getting-started');

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

  // Envoyer un message au chat
  window.GitBook('postUserMessage', 'How do I get started?');

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

Charger dynamiquement (optionnel)

Pour des docs authentifiés ou un chargement conditionnel, injectez le script à l'exécution :

<script>
  function loadGitBookEmbed() {
    var script = document.createElement("script");
    script.src = "https://docs.company.com/~gitbook/embed/script.js";
    script.async = true;
    script.onload = function () {
      window.GitBook('init', { siteURL: 'https://docs.company.com' });
      window.GitBook("show");
    };
    document.head.appendChild(script);
  }

  // Charger quand prêt
  loadGitBookEmbed();
</script>
9

Vérifiez la configuration

Ouvrez la console de votre navigateur et tapez window.GitBook pour confirmer que l'API est disponible.

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

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 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', {...}):

onglets

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

  • 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'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[]

tools

Outils IA personnalisés pour étendre l'Assistant. Voir Creating custom tools pour plus de 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 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é)

Transmettez 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) - 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 vos docs, pas l'exemple docs.company.com.

  • Appeler GitBook avant le chargement du script – Enveloppez les appels API dans script.onload ou placez-les après la balise script.

  • Docs authentifiés non accessibles – Si vos docs nécessitent une connexion, vous devez fournir le visitor.token lors de l'initialisation. Voir Using with authenticated docs.

  • Erreurs CORS ou CSP – Assurez-vous que la politique de sécurité de contenu de votre site permet 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

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