Référence API

En savoir plus sur les méthodes disponibles à utiliser lorsque vous travaillez avec Docs Embed de manière programmatique

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 selon les 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="...">
Remplacement du schéma de couleurs	GitBook('init', options, { colorScheme })	client.getFrameURL({ colorScheme })	<GitBookFrame colorScheme="..." />
Obtenir l'URL du frame	❌ (géré en interne)	client.getFrameURL(options)	useGitBook().getFrameURL(options)
Créer le client du 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 du frame
Naviguer vers l'assistant	GitBook('navigateToAssistant')	frame.navigateToAssistant()	Via le client du frame
Publier un message	GitBook('postUserMessage', message)	frame.postUserMessage(message)	Via le client du frame
Vider le chat	GitBook('clearChat')	frame.clearChat()	Via le client du frame
Configurer	GitBook('configure', settings)	frame.configure(settings)	Props de <GitBookFrame>
Écouteurs d'événements	❌	frame.on(event, listener)	Via le client du 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é facultatif.

Paramètres :

• options: { siteURL: string } - L'URL du site de documentation GitBook
• frameOptions: { visitor?: { token?: string, unsignedClaims?: Record<string, unknown> }, colorScheme?: 'light' | 'dark' } (facultatif) - Options du frame

Exemple :

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

Lorsque colorScheme est omis, suit le color-scheme.

CSS de l'iframe

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 à l'aide de son chemin.

Paramètres :

• path (string): Le chemin de 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 :

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

// Vous pourriez 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 à publier dans le chat

Exemple :

// Envoyer un message prédéfini
window.GitBook("postUserMessage", "Comment réinitialiser mon mot de passe ?");

// Envoyer un message en fonction de l'action de l'utilisateur
function askAboutBilling() {
  window.GitBook("postUserMessage", "J'ai des questions sur ma facturation");
}

// Envoyer un message avec contexte
const userPlan = "premium";
window.GitBook(
  "postUserMessage",
  `Je suis sur l'offre ${userPlan} et j'ai besoin d'aide pour les 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 repartir sur une nouvelle conversation
function startNewConversation() {
  window.GitBook("clearChat");
  window.GitBook("postUserMessage", "Bonjour, j'ai besoin d'aide pour un nouveau problème");
}

// 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. Voir la section de configuration pour les options disponibles.

Exemple :

window.GitBook('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: ['Qu'est-ce que GitBook ?', 'Comment puis-je commencer ?']
});

API du package NPM

Fabrique de client

createGitBook(options)

Créez une instance client GitBook.

Paramètres :

• options: { siteURL: string } - L'URL du 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> }, colorScheme?: 'light' | 'dark' } (facultatif)

Renvoie : string

Exemple :

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

client.createFrame(iframe)

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

frame.navigateToPage(path)

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

Paramètres :

• path: string - Le chemin de la page

frame.navigateToAssistant()

Basculez vers l'onglet assistant.

frame.postUserMessage(message)

Publiez 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. Voir la section de configuration pour les options disponibles.

frame.on(event, listener)

Enregistrez un écouteur d'événements.

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 fermé');
});

// Plus tard, désabonnez-vous
unsubscribe();

API des composants React

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

GitBookFrame prend en charge assistantName, closeButton, colorScheme="light" | "dark", ainsi que la visitor prop pour l'accès authentifié.

useGitBook().getFrameURL() accepte le même colorScheme paramètre que le package NPM.