Référence de l’API

Découvrez davantage les méthodes disponibles à utiliser lors de l’utilisation programmatique de Docs Embed

Docs Embed fournit différentes API selon la façon dont vous l'intégrez. Cette référence couvre toutes les méthodes disponibles selon les méthodes 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 frame	❌ (géré en interne)	client.getFrameURL(options)	useGitBook().getFrameURL(options)
Créer un client de frame	❌ (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 une page	GitBook('navigateToPage', path)	frame.navigateToPage(path)	Via le client de frame
Naviguer vers l'assistant	GitBook('navigateToAssistant')	frame.navigateToAssistant()	Via le client de frame
Envoyer un message	GitBook('postUserMessage', message)	frame.postUserMessage(message)	Via le client de frame
Effacer le chat	GitBook('clearChat')	frame.clearChat()	Via le client de frame
Configurer	GitBook('configure', settings)	frame.configure(settings)	Props sur <GitBookFrame>
Écouteurs d'événements	❌	frame.on(event, listener)	Via le client de frame
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é optionnel.

Paramètres :

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

• frameOptions: { visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } } (optionnel) - 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

Afficher le widget GitBook s'il a été masqué.

Exemple :

window.GitBook("show");

Masquer le widget

Masquer le widget GitBook sans le décharger.

Exemple :

window.GitBook("hide");

Ouvrir la fenêtre

Ouvrir la fenêtre Docs Embed.

Exemple :

window.GitBook("open");

Fermer la fenêtre

Fermer la fenêtre Docs Embed.

Exemple :

window.GitBook("close");

Basculer la fenêtre

Basculer l'état ouvert/fermé de la fenêtre Docs Embed.

Exemple :

window.GitBook("toggle");

Décharger le widget

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

• path (string) : Le chemin vers la page vers laquelle vous voulez 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 :

// Basculer vers l'onglet assistant
window.GitBook("navigateToAssistant");

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

Chat

GitBook('postUserMessage', message)

Publiez un message dans le chat comme si l'utilisateur l'avait tapé.

Paramètres :

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

Exemple :

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

// Envoyer un message basé sur une action utilisateur
function askAboutBilling() {
  window.GitBook("postUserMessage", "I have questions about my billing");
}

// Envoyer un message avec contexte
const userPlan = "premium";
window.GitBook(
  "postUserMessage",
  `I'm on the ${userPlan} plan and need help with advanced features`
);

GitBook('clearChat')

Effacez tous les messages de la session de chat en cours.

Exemple :

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

// Effacer le chat et commencer 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'embed avec des options de personnalisation. Voir la section Configuration pour les options disponibles.

Exemple :

window.GitBook('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?']
});

API du package NPM

Usine de clients

createGitBook(options)

Créez 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é optionnel.

Paramètres :

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

Renvoie : string

Exemple :

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

client.createFrame(iframe)

Créez un client de frame 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 frame

frame.navigateToPage(path)

Naviguez vers une page spécifique dans l'onglet docs.

Paramètres :

• path: string - Le chemin vers la page

frame.navigateToAssistant()

Basculer vers l'onglet assistant.

frame.postUserMessage(message)

Envoyer un message au chat.

Paramètres :

• message: string - Le message à envoyer

frame.clearChat()

Effacer l'historique du chat.

frame.configure(settings)

Configurer l'embed. Voir la section Configuration pour les options disponibles.

frame.on(event, listener)

Enregistrer un écouteur d'événement.

Paramètres :

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

• listener: Fonction - 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

Voir la guide d'intégration React pour les props des composants et le useGitBook hook API.