Référence de l’API

En savoir plus sur les méthodes disponibles à utiliser lors de l’utilisation programmatique de Docs Embed

Docs Embed propose différentes API selon la manière dont vous l’intégrez. Cette référence couvre toutes les méthodes disponibles pour les différents modes d’intégration.

Comparaison des méthodes

Méthode	Script autonome	Package NPM	Composants React
Initialiser	GitBook('init', options, frameOptions)	createGitBook(options)	<GitBookProvider siteURL="...">
Obtenir l’URL du cadre	❌ (géré en interne)	client.getFrameURL(options)	useGitBook().getFrameURL(options)
Créer un client de cadre	❌ (géré en interne)	client.createFrame(iframe)	useGitBook().createFrame(iframe)
Afficher/Masquer le widget	GitBook('show') / GitBook('hide')	❌	❌
Ouvrir/Fermer la fenêtre	GitBook('open') / GitBook('close') / GitBook('toggle')	❌	❌
Naviguer vers la page	GitBook('navigateToPage', path)	frame.navigateToPage(path)	Via le client du cadre
Naviguer vers l’assistant	GitBook('navigateToAssistant')	frame.navigateToAssistant()	Via le client du cadre
Publier un message	GitBook('postUserMessage', message)	frame.postUserMessage(message)	Via le client du cadre
Effacer le chat	GitBook('clearChat')	frame.clearChat()	Via le client du cadre
Configurer	GitBook('configure', settings)	frame.configure(settings)	Props sur <GitBookFrame>
Écouteurs d’événements	❌	frame.on(event, listener)	Via le client du cadre
Décharger	GitBook('unload')	❌	❌

API du script autonome

Initialisation

GitBook('init', options, frameOptions)

Initialisez le widget avec l’URL du site et un accès authentifié facultatif.

Paramètres :

• options: { siteURL: string } - L’URL de votre site de documentation GitBook

• frameOptions: { visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } } (facultatif) - Options d’accès authentifié

Exemple :

window.GitBook('init', 
  { siteURL: 'https://docs.company.com' },
  { visitor: { token: 'your-jwt-token' } }
);

Contrôle du widget

Afficher le widget

Affiche le widget GitBook s’il a été masqué.

Exemple :

window.GitBook("show");

Masquer le widget

Masque le widget GitBook sans le décharger.

Exemple :

window.GitBook("hide");

Ouvrir la fenêtre

Ouvre la fenêtre Docs Embed.

Exemple :

window.GitBook("open");

Fermer la fenêtre

Ferme la fenêtre Docs Embed.

Exemple :

window.GitBook("close");

Basculer la fenêtre

Bascule l’ouverture ou la fermeture de la fenêtre Docs Embed.

Exemple :

window.GitBook("toggle");

Décharger le widget

Supprime complètement le widget GitBook de votre site.

Exemple :

window.GitBook("unload");

Navigation

GitBook('navigateToPage', path)

Naviguez vers une page spécifique de votre documentation GitBook par son chemin.

Paramètres :

• chemin (string) : Le chemin vers la page vers laquelle vous souhaitez naviguer

Exemple :

// Naviguer vers le guide de démarrage
window.GitBook("navigateToPage", "/getting-started");

// Naviguer vers une page de documentation API spécifique
window.GitBook("navigateToPage", "/api/authentication");

// Naviguer vers la section FAQ
window.GitBook("navigateToPage", "/faq/billing");

GitBook('navigateToAssistant')

Naviguez directement vers l’onglet Assistant.

Exemple :

// Passer à l’onglet assistant
window.GitBook("navigateToAssistant");

// Vous pourriez utiliser cela en réponse à un clic sur un bouton
document.getElementById("help-button").addEventListener("click", () => {
  window.GitBook("navigateToAssistant");
});

Chat

GitBook('postUserMessage', message)

Publie un message dans le chat comme si l’utilisateur l’avait saisi.

Paramètres :

• message (string) : Le message à publier dans le chat

Exemple :

// Envoyer un message prédéfini
window.GitBook("postUserMessage", "How do I reset my password?");

// Envoyer un message en fonction de l’action de l’utilisateur
function askAboutBilling() {
  window.GitBook("postUserMessage", "I have questions about my billing");
}

// Envoyer un message avec contexte
const userPlan = "premium";
window.GitBook(
  "postUserMessage",
  `Je suis sur le forfait ${userPlan} et j’ai besoin d’aide pour des fonctionnalités avancées`
);

GitBook('clearChat')

Efface tous les messages de la session de chat actuelle.

Exemple :

// Effacer le chat
window.GitBook("clearChat");

// Effacer le chat et démarrer une nouvelle conversation
function startNewConversation() {
  window.GitBook("clearChat");
  window.GitBook("postUserMessage", "Hello, I need help with a new issue");
}

// Effacer le chat lors du changement de contexte
document.getElementById("new-topic").addEventListener("click", () => {
  window.GitBook("clearChat");
  window.GitBook("navigateToAssistant");
});

Configuration

GitBook('configure', settings)

Configurez l’intégration avec des options de personnalisation. Consultez la section Configuration pour connaître les options disponibles.

Exemple :

window.GitBook('configure', {
  trademark: false,
  tabs: ['assistant', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: 'Contacter le support',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'Bienvenue !', subtitle: 'Comment puis-je aider ?' },
  suggestions: ['Qu’est-ce que GitBook ?', 'Comment démarrer ?']
});

API du package NPM

Fabrique de client

createGitBook(options)

Crée une instance de client GitBook.

Paramètres :

• options: { siteURL: string } - L’URL de votre site de documentation GitBook

Renvoie : GitBookClient

Exemple :

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

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

client.getFrameURL(options)

Obtenez l’URL de l’iframe avec un accès authentifié facultatif.

Paramètres :

• options: { visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } } (facultatif)

Renvoie : string

Exemple :

const iframeURL = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token',
    unsignedClaims: { userId: '123', plan: 'premium' }
  }
});

client.createFrame(iframe)

Crée un client de cadre pour communiquer avec l’iframe.

Paramètres :

• iframe: HTMLIFrameElement - L’élément iframe

Renvoie : GitBookFrameClient

Exemple :

const iframe = document.createElement('iframe');
iframe.src = gitbook.getFrameURL();
const frame = gitbook.createFrame(iframe);

Méthodes du client de cadre

frame.navigateToPage(path)

Naviguez vers une page spécifique dans l’onglet de documentation.

Paramètres :

• chemin: string - Le chemin vers la page

frame.navigateToAssistant()

Passez à l’onglet assistant.

frame.postUserMessage(message)

Publie un message dans le chat.

Paramètres :

• message: string - Le message à publier

frame.clearChat()

Efface l’historique du chat.

frame.configure(settings)

Configurez l’intégration. Consultez la section Configuration pour connaître les options disponibles.

frame.on(event, listener)

Enregistre un écouteur d’événement.

Paramètres :

• event: string - Le nom de l’événement

• listener: Function - La fonction de rappel

Renvoie : () => void - Fonction de désabonnement

Exemple :

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

// Plus tard, se désabonner
unsubscribe();

API des composants React

Consultez le guide d’intégration React pour les props des composants et le useGitBook API du hook.