React

Utilisez des composants React préconstruits pour ajouter Docs Embed à votre application React

Pour les projets React, GitBook fournit des composants préconstruits qui facilitent l'intégration de votre documentation de manière simple et idiomatique. Les composants gèrent automatiquement la gestion d'état, le contexte et le cycle de vie.

Étapes

1

Installer le package

Ajouter @gitbook/embed à votre projet React :

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

Importer les composants React

Importer le GitBookProvider et GitBookFrame composants :

import {
  GitBookProvider,
  GitBookFrame,
} from "@gitbook/embed/react";

3

Envelopper votre application avec GitBookProvider

Ajoutez le provider à la racine de votre arbre de composants ou là où vous avez besoin de l'intégration :

function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <YourAppContent />
    </GitBookProvider>
  );
}

4

Ajouter le composant GitBookFrame

Placez le composant frame à l'endroit où vous souhaitez que l'intégration apparaisse :

function App() {
  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <div className="app">
        <YourAppContent />
        <GitBookFrame
          visitor={{
            token: 'your-jwt-token', // Optionnel : pour le contenu adaptatif ou l'accès authentifié
            unsignedClaims: { userId: '123' } // Optionnel : claims personnalisés pour des expressions dynamiques
          }}
        />
      </div>
    </GitBookProvider>
  );
}

5

Personnaliser l'intégration

Passez des props de configuration au composant frame :

<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    trademark={false}
    tabs={['assistant', 'docs']}
    greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
    suggestions={['What is GitBook?', 'How do I get started?']}
    actions={[
      {
        icon: 'circle-question',
        label: 'Contact Support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ]}
    tools={[/* ... */]}
    visitor={{
      token: 'your-jwt-token',
      unsignedClaims: { userId: '123' }
    }}
  />
</GitBookProvider>

6

Contrôler l'intégration avec le hook useGitBook

Utilisez le useGitBook hook pour interagir avec l'intégration de manière programmatique :

import { useGitBook } from "@gitbook/embed/react";

function HelpButton() {
  const gitbook = useGitBook();
  const frameURL = gitbook.getFrameURL({ visitor: { token: '...' } });
  
  const handleNavigate = () => {
    const iframe = document.createElement('iframe');
    iframe.src = frameURL;
    const frame = gitbook.createFrame(iframe);
    frame.navigateToPage('/getting-started');
    frame.navigateToAssistant();
    frame.postUserMessage('How do I get started?');
  };

  return <button onClick={handleNavigate}>Get Help</button>;
}

7

Rendre l'intégration de façon conditionnelle

Afficher l'intégration uniquement lorsque nécessaire :

function App() {
  const [showEmbed, setShowEmbed] = useState(false);

  return (
    <GitBookProvider siteURL="https://docs.company.com">
      <button onClick={() => setShowEmbed(true)}>Get Help</button>
      {showEmbed && <GitBookFrame />}
    </GitBookProvider>
  );
}

8

Utilisation avec Next.js ou rendu côté serveur

Importer dynamiquement les composants pour éviter les problèmes SSR :

import dynamic from "next/dynamic";

const GitBookProvider = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookProvider),
  { ssr: false }
);

const GitBookFrame = dynamic(
  () => import("@gitbook/embed/react").then((mod) => mod.GitBookFrame),
  { ssr: false }
);

Props & Configuration

Props de GitBookProvider :

Prop	Type	Requis	Par défaut	Description
siteURL	string	Oui	N/A	L'URL de votre site de docs GitBook (par ex., https://docs.company.com).
children	ReactNode	Oui	N/A	Composants enfants à rendre dans le provider.

Props de GitBookFrame :

Toutes les options de configuration peuvent être passées en tant que props à <GitBookFrame>. Voir la section Configuration ci‑dessous pour les options disponibles.

Prop	Type	Requis	Par défaut	Description
className	string	Non	null	Nom de classe CSS à appliquer au conteneur du frame.
style	object	Non	{}	Styles en ligne à appliquer au conteneur du frame.
visitor	object	Non	{}	Options d'accès authentifié (voir ci‑dessous).

Hook useGitBook :

Retourne une GitBookClient instance avec les méthodes suivantes :

• getFrameURL(options?: { visitor?: {...} }) → string - Obtenir l'URL de l'iframe

• createFrame(iframe: HTMLIFrameElement) → GitBookFrameClient - Créer un client de frame

Le client de frame fournit :

• navigateToPage(path: string) → void

• navigateToAssistant() → void

• postUserMessage(message: string) → void

• clearChat() → void

• configure(settings: {...}) → void

• on(event: string, listener: Function) → () => void

Options de configuration

Les options de configuration sont disponibles en tant que props sur <GitBookFrame>:

tabs

Remplace les onglets affichés. Par défaut, utilise la configuration de votre site.

• 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 lors du clic.

Remarque : Ceci était auparavant nommé 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 dans l'écran de bienvenue de l'Assistant.

• Type: string[]

trademark

Afficher ou masquer la marque GitBook dans l'interface intégrée — y compris le pied de page Docs Embed et l'image de marque de l'Assistant.

• Type: boolean

• Par défaut: true

tools

Outils IA personnalisés pour étendre l'Assistant. Voir Creating custom tools pour les détails.

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

visitor (Authenticated Access)

Utilisé pour Adaptive Content et Authenticated Access.

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

Pièges courants

• Ne pas envelopper avec GitBookProvider – Le GitBookFrame requiert un parent GitBookProvider pour fonctionner.

• Utilisation avec SSR sans import dynamique – Le composant utilise des API du navigateur et doit être importé dynamiquement dans Next.js ou d'autres frameworks SSR.

• siteURL ne correspondant pas à la docs publiée – Assurez‑vous que la prop siteURL correspond exactement à l'URL de votre site de documentation en ligne.

• Appeler useGitBook en dehors du provider – Le useGitBook le hook doit être utilisé dans un composant qui est enfant de GitBookProvider.

• Plusieurs providers dans l'arbre – Évitez d'imbriquer plusieurs GitBookProvider instances, car cela peut provoquer des conflits de contexte.

• Utilisation d'anciens noms de composants – Le composant est maintenant GitBookFrame, pas GitBookAssistantFrame.