Node.js/NPM

Intégrez Docs Embed à l’aide du package NPM pour un contrôle complet au niveau de l’application

Si vous avez besoin de plus de contrôle et souhaitez travailler au niveau de l’application, vous pouvez installer le package d’intégration GitBook depuis npm. Cette approche est idéale pour le rendu côté serveur, l’intégration au moment de la compilation ou la gestion personnalisée des iframes.

Étapes

1

Installez le package

Ajoutez @gitbook/embed dans votre projet :

npm install @gitbook/embed

Pour la référence complète de l’API et le code source, voir le @gitbook/embed package sur GitHub.

2

Importez le package

Dans le code de votre application, importez la createGitBook fonction :

import { createGitBook } from "@gitbook/embed";

Ou en utilisant CommonJS :

const { createGitBook } = require("@gitbook/embed");

3

Initialisez GitBook

Créez une instance GitBook avec l’URL de votre site de documentation :

const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});

4

Créez une iframe

Générez un élément iframe et définissez sa source sur l’URL d’intégration :

const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token', // Facultatif : pour le contenu adaptatif ou l’accès authentifié
    unsignedClaims: { // Facultatif : revendications personnalisées pour les expressions dynamiques
      userId: '123',
      plan: 'premium'
    }
  }
});
iframe.id = "gitbook-embed-container";
iframe.style.border = "none";
iframe.style.width = "100%";
iframe.style.height = "600px";
iframe.allow = "clipboard-write";

Si vous utilisez l’onglet Assistant, définissez allow="clipboard-write" sur l’iframe. Le package NPM vous laisse configurer l’iframe. L’implémentation balise script autonome l’ajoute automatiquement.

5

Attachez le cadre

Créez une instance de cadre GitBook et intégrez-la à votre page :

const frame = gitbook.createFrame(iframe);
document.getElementById("gitbook-embed-container").appendChild(iframe);

6

Contrôlez l’intégration par programme

Utilisez l’instance de cadre pour interagir avec l’intégration :

// Naviguer vers une page spécifique dans l’onglet Docs
frame.navigateToPage("/getting-started");

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

// Publier un message dans le chat
frame.postUserMessage("How do I get started?");

// Effacer l’historique du chat
frame.clearChat();

7

Configurez l’intégration

Configurez l’intégration avec des options de personnalisation :

frame.configure({
  trademark: false,
  tabs: ['assistant', 'search', '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 ?' },
  assistantName: 'Copilote d'assistance',
  closeButton: true,
  suggestions: ['What is GitBook?', 'How do I get started?'],
  tools: [/* ... */]
});

8

Écoutez les événements

Enregistrez des écouteurs d’événements pour réagir aux événements de l’intégration :

frame.on('close', () => {
  console.log('Frame fermé');
});

// Se désabonner une fois terminé
const unsubscribe = frame.on('navigate', (data) => {
  console.log('Navigué vers :', data.path);
});

Référence de l’API

Fabrique de client

• createGitBook(options: { siteURL: string }) → GitBookClient
• client.getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' }) → string - Obtenir l’URL de l’iframe avec des options de cadre facultatives
• client.createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - Créer un client de cadre pour communiquer avec l’iframe

Méthodes du client du frame

• frame.navigateToPage(path: string) → vide - Naviguer vers une page spécifique dans l’onglet Docs
• frame.navigateToAssistant() → vide - Passer à l’onglet Assistant
• frame.postUserMessage(message: string) → vide - Publier un message dans le chat
• frame.clearChat() → vide - Effacer l’historique du chat
• frame.configure(settings: Partial<GitBookEmbeddableConfiguration>) → vide - Configurer l’intégration
• frame.on(event: string, listener: Function) → () => void - Enregistrer un écouteur d’événements (renvoie une fonction de désabonnement)

Options de configuration

La plupart des options de personnalisation sont disponibles via frame.configure({...}).

les onglets

Remplacez les onglets affichés.

La recherche est activée par défaut. Si vous définissez les onglets, l’embed n’affiche que les onglets que vous listez.

• Tapez: ('assistant' | 'search' | 'docs')[]

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: Ceci s’appelait auparavant buttons. Utilisez actions à la place.

• Tapez: Array<{ icon: string, label: string, onClick: () => void }>

greeting

Message de bienvenue affiché dans l’onglet Assistant.

• Tapez: { title: string, subtitle: string }

assistantName

Remplacez le nom de l’assistant affiché dans l’interface.

• Tapez: string
• Longueur maximale: 32 caractères

closeButton

Affiche un bouton de fermeture dans l’Assistant.

• Tapez: booléen

suggestions

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

• Tapez: string[]

marque déposée

Afficher ou masquer la marque GitBook dans l’interface de l’intégration — y compris le pied de page de l’intégration Docs et l’image de marque de l’Assistant.

• Tapez: booléen
• Par défaut: vrai

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?: {...} }>

Options de l’URL du cadre

Certaines options sont transmises à getFrameURL({...}).

colorScheme

Remplacez le jeu de couleurs de l’intégration.

Lorsqu’elle est omise, l’intégration suit le CSS de l’iframe color-scheme, ce qui lui permet d’hériter du parent de la page ou de la préférence du navigateur.

• Tapez: 'light' | 'dark'

visitor (Accès authentifié)

Transmettez à getFrameURL({ visitor: {...} }). Utilisé pour Contenu adaptatif et Accès authentifié.

• Tapez: { token?: string, unsignedClaims?: Record<string, unknown> }

Pièges courants

• Oublier d’installer le package – Exécutez npm install @gitbook/embed avant d’importer.
• siteURL manquant – L’option siteURL est requise et doit correspondre à votre site de documentation publié.
• L’iframe ne s’affiche pas – Assurez-vous que le conteneur parent dispose d’une largeur/hauteur suffisante pour afficher l’iframe.
• Méthodes du cadre appelées avant l’initialisation – Attendez que createFrame() soit terminé avant d’appeler les méthodes du cadre.
• Ne pas se désabonner des événements – N’oubliez pas d’appeler la fonction de désabonnement renvoyée par frame.on() pour éviter les fuites mémoire.
• Utilisation d’anciennes méthodes de l’API – Les méthodes comme open(), close(), toggle(), et destroy() ne sont pas disponibles dans le package NPM. Utilisez plutôt les méthodes du client de cadre.