Balise script

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

La manière 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 documentation dans GitBook inclut un script prêt à l'emploi pour intégrer vos docs en tant que widget.

Étapes

Obtenez l'URL du script d'intégration

Allez dans le 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 documentation).

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 un accès authentifié (optionnel)
  window.GitBook('init', 
    { siteURL: 'https://docs.company.com' },
    { visitor: { token: 'your-jwt-token' } }
  );
  window.GitBook('show');
</script>

Remplacez l'URL des docs

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

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

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>

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>

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

  // Passer à 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>

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>

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

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

`onglets`

Remplacez les onglets affichés. Par défaut, ils correspondent à la configuration de votre site.

Type: ('assistant' | 'docs')[]
Options:
- ['assistant', 'docs'] - Afficher les deux onglets
- ['assistant'] - N'afficher que l'onglet assistant
- ['docs'] - N'afficher que 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 était précédemment nommé 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
- libellé: string - Texte du label 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 de bienvenue 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?: {...} }>

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

Type: { 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 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.
Appel de GitBook avant le chargement du script – Enveloppez les appels API dans script.onload ou placez-les après la balise script.
Docs authentifiées non accessibles – Si vos docs nécessitent 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 (CSP) 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 1 mois

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

Bonne nuit

Balise script

Étapes

Obtenez l'URL du script d'intégration

Ajoutez la balise script à votre HTML

Remplacez l'URL des docs

Testez le widget

Configurer éventuellement l'intégration

Contrôler la visibilité du widget

Naviguer et interagir par programmation

Charger dynamiquement (optionnel)

Vérifiez la configuration

Référence API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`onglets`

`actions`

`greeting`

`suggestions`

`tools`

`bouton`

`visitor` (Accès authentifié)

Pièges courants

Bonne nuit

hashtagÉtapes

hashtagObtenez l'URL du script d'intégration

hashtagAjoutez la balise script à votre HTML

hashtagRemplacez l'URL des docs

hashtagTestez le widget

hashtagConfigurer éventuellement l'intégration

hashtagContrôler la visibilité du widget

hashtagNaviguer et interagir par programmation

hashtagCharger dynamiquement (optionnel)

hashtagVérifiez la configuration

hashtagRéférence API

hashtagInitialisation

hashtagContrôle du widget

hashtagNavigation

hashtagChat

hashtagConfiguration

hashtagOptions de configuration

hashtagonglets

hashtagactions

hashtaggreeting

hashtagsuggestions

hashtagtools

hashtagbouton

hashtagvisitor (Accès authentifié)

hashtagPièges courants

Étapes

Obtenez l'URL du script d'intégration

Ajoutez la balise script à votre HTML

Remplacez l'URL des docs

Testez le widget

Configurer éventuellement l'intégration

Contrôler la visibilité du widget

Naviguer et interagir par programmation

Charger dynamiquement (optionnel)

Vérifiez la configuration

Référence API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`onglets`

`actions`

`greeting`

`suggestions`

`tools`

`bouton`

`visitor` (Accès authentifié)

Pièges courants