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

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

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>

Si votre site de docs est protégé par un accès authentifié, le script lui-même est servi derrière une authentification. Ajoutez le jeton signé à l'URL du script en tant que jwt_token:

https://docs.company.com/~gitbook/embed/script.js?jwt_token=your-jwt-token

Remplacez l'URL des docs

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

Chargez votre page. Le widget intégré devrait apparaître en bas à droite.

Configurer optionnellement 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 programmatiquement

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");
    // Si votre site de docs est protégé, vous devez authentifier la requête du script.
    // Ajoutez le jeton signé en tant que `jwt_token`.
    var token = "your-jwt-token";
    script.src =
      "https://docs.company.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    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érifier la configuration

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

Référence de l'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') - Retirer 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, cela correspond à 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 aux côtés 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 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[]

`outils`

Outils d'IA personnalisés pour étendre l'Assistant. Voir Créer des outils personnalisés 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 en bas à droite 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 via la balise 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 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 inaccessibles – Si vos docs exigent une connexion, vous devez fournir le visitor.token lors de l'initialisation. Voir Utilisation avec des docs authentifiés.
Erreurs CORS ou CSP – Assurez-vous que la politique de sécurité du 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 il y a 7 jours

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

Bonne nuit

Balise script

Étapes

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

Ajoutez la balise script à votre HTML

Remplacez l'URL des docs

Testez le widget

Configurer optionnellement l'intégration

Contrôler la visibilité du widget

Naviguer et interagir programmatiquement

Charger dynamiquement (optionnel)

Vérifier la configuration

Référence de l'API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`onglets`

`actions`

`greeting`

`suggestions`

`outils`

`button`

`visitor` (Accès authentifié)

Pièges courants

Bonne nuit

hashtagÉtapes

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

hashtagAjoutez la balise script à votre HTML

hashtagRemplacez l'URL des docs

hashtagTestez le widget

hashtagConfigurer optionnellement l'intégration

hashtagContrôler la visibilité du widget

hashtagNaviguer et interagir programmatiquement

hashtagCharger dynamiquement (optionnel)

hashtagVérifier la configuration

hashtagRéférence de l'API

hashtagInitialisation

hashtagContrôle du widget

hashtagNavigation

hashtagChat

hashtagConfiguration

hashtagOptions de configuration

hashtagonglets

hashtagactions

hashtaggreeting

hashtagsuggestions

hashtagoutils

hashtagbutton

hashtagvisitor (Accès authentifié)

hashtagPièges courants

Étapes

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

Ajoutez la balise script à votre HTML

Remplacez l'URL des docs

Testez le widget

Configurer optionnellement l'intégration

Contrôler la visibilité du widget

Naviguer et interagir programmatiquement

Charger dynamiquement (optionnel)

Vérifier la configuration

Référence de l'API

Initialisation

Contrôle du widget

Navigation

Chat

Configuration

Options de configuration

`onglets`

`actions`

`greeting`

`suggestions`

`outils`

`button`

`visitor` (Accès authentifié)

Pièges courants