Node.js/NPM

Intégrez Docs Embed en utilisant le 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 GitBook embed depuis npm. Cette approche est idéale pour le rendu côté serveur, l'intégration au moment de la construction ou la gestion personnalisée des iframes.

Étapes

1

Installer le package

Ajouter @gitbook/embed à votre projet :

npm install @gitbook/embed

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

2

Importer 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

Initialiser GitBook

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

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

4

Créer un 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', // Optionnel : pour le contenu adaptatif ou l'accès authentifié
    unsignedClaims: { // Optionnel : revendications personnalisées pour des expressions dynamiques
      userId: '123',
      plan: 'premium'
    }
  }
});
iframe.id = "gitbook-embed-container";
iframe.style.border = "none";
iframe.style.width = "100%";
iframe.style.height = "600px";

5

Attacher le frame

Créez une instance de frame GitBook et montez-la sur votre page :

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

6

Contrôler l'intégration par programmation

Utilisez l'instance frame pour interagir avec l'intégration :

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

// Passer à l'onglet assistant
frame.navigateToAssistant();

// Envoyer un message au chat
frame.postUserMessage("How do I get started?");

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

7

Configurer l'intégration

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

frame.configure({
  trademark: false,
  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?'],
  tools: [/* ... */]
});

8

Écouter les événements

Enregistrez des écouteurs d'événements pour répondre aux événements de l'intégration :

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

// Se désabonner lorsque c'est terminé
const unsubscribe = frame.on('navigate', (data) => {
  console.log('Navigated to:', data.path);
});

Référence API

Usine cliente

• createGitBook(options: { siteURL: string }) → GitBookClient

• client.getFrameURL(options?: { visitor?: {...} }) → string - Obtenir l'URL de l'iframe avec un accès authentifié optionnel

• client.createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - Créer un client de frame pour communiquer avec l'iframe

Méthodes du client Frame

• frame.navigateToPage(path: string) → void - Naviguer vers une page spécifique dans l'onglet docs

• frame.navigateToAssistant() → void - Basculer vers l'onglet assistant

• frame.postUserMessage(message: string) → void - Envoyer un message au chat

• frame.clearChat() → void - Effacer l'historique du chat

• frame.configure(settings: Partial<GitBookEmbeddableConfiguration>) → void - Configurer l'intégration

• frame.on(event: string, listener: Function) → () => void - Enregistrer un écouteur d'événement (renvoie une fonction de désabonnement)

Options de configuration

Les options de configuration sont disponibles via frame.configure({...}):

onglets

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

• Type: ('assistant' | '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'il est cliqué.

Remarque: Ceci s'appelait auparavant buttons. Utilisez actions à la place.

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

greeting

Message de bienvenue affiché dans l'onglet Assistant.

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

suggestions

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

• Type: 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 le branding de l'Assistant.

• Type: boolean

• Par défaut: true

tools

Outils IA personnalisés pour étendre l'Assistant. Voir Créer des outils personnalisés pour les détails.

• Type: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

visitor (Accès Authentifié)

Passez à getFrameURL({ visitor: {...} }). Utilisé pour Contenu Adaptatif et Accès Authentifié.

• Type: { 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é.

• iFrame ne s'affiche pas – Assurez-vous que le conteneur parent a une largeur/hauteur suffisante pour afficher l'iframe.

• Méthodes de Frame appelées avant l'initialisation – Attendez que createFrame() se termine avant d'appeler les méthodes du frame.

• 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 de mémoire.

• Utilisation d'anciennes méthodes API – Des méthodes comme open(), close(), toggle(), et destroy() ne sont pas disponibles dans le package NPM. Utilisez plutôt les méthodes du client frame.