# React

Pour les projets React, GitBook fournit des composants préconstruits qui rendent l’intégration de votre documentation simple et idiomatique. Les composants gèrent automatiquement l’état, le contexte et le cycle de vie.

## Étapes

{% stepper %}
{% step %}
**Installez le package**

Ajoutez `@gitbook/embed` à votre projet React :

```bash
npm install @gitbook/embed
```

Pour la référence complète de l’API et le code स्रोत, consultez le package [`@gitbook/embed` sur GitHub](https://github.com/GitbookIO/gitbook/tree/main/packages/embed).
{% endstep %}

{% step %}
**Importez les composants React**

Importez le `GitBookProvider` et `GitBookFrame` components:

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

{% endstep %}

{% step %}
**Encapsulez votre application avec GitBookProvider**

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

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

{% endstep %}

{% step %}
**Ajoutez le composant GitBookFrame**

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

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

{% endstep %}

{% step %}
**Personnalisez l’intégration**

Passez des props de configuration au composant frame :

```jsx
<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    trademark={false}
    tabs={['assistant', 'search', 'docs']}
    colorScheme="dark"
    greeting={{ title: 'Welcome!', subtitle: 'How can I help?' }}
    assistantName="Support Copilot"
    closeButton={true}
    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>
```

Si vous omettez `colorScheme`, l’intégration suit le CSS de l’iframe `color-scheme`. Cela lui permet de s’adapter automatiquement au thème de votre application.
{% endstep %}

{% step %}
**Contrôlez l’intégration avec le hook useGitBook**

Utilisez le `useGitBook` hook pour interagir avec l’intégration par programmation :

```jsx
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>;
}
```

{% endstep %}

{% step %}
**Rendez l’intégration conditionnelle**

Affichez l’intégration uniquement lorsque c’est nécessaire :

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

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

{% endstep %}

{% step %}
**Utilisez avec Next.js ou le rendu côté serveur**

Importez dynamiquement les composants pour éviter les problèmes de SSR :

```jsx
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 }
);
```

{% endstep %}
{% endstepper %}

## Propriétés et configuration

**Propriétés de GitBookProvider :**

| Prop       | Tapez       | Requis | Par défaut | Description                                                                         |
| ---------- | ----------- | ------ | ---------- | ----------------------------------------------------------------------------------- |
| `siteURL`  | `string`    | Oui    | N/A        | L’URL de votre site de documentation GitBook (par ex.  `https://docs.company.com`). |
| `children` | `ReactNode` | Oui    | N/A        | Composants enfants à rendre au sein du provider.                                    |

**Propriétés de GitBookFrame :**

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

| Prop            | Tapez               | 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.                   |
| `colorScheme`   | `'light' \| 'dark'` | Non    | Hérite du CSS `color-scheme` | Remplace le schéma de couleurs de l’intégration.                     |
| `assistantName` | `string`            | Non    | `null`                       | Remplace le nom de l’assistant affiché dans l’interface utilisateur. |
| `closeButton`   | `boolean`           | Non    | `null`                       | Affiche un bouton de fermeture dans l’Assistant.                     |
| `visitor`       | `object`            | Non    | `{}`                         | Options d’accès authentifié (voir ci-dessous).                       |

**Hook useGitBook :**

Renvoie une `GitBookClient` instance avec les méthodes suivantes :

* `getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' })` → `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>`:

### `onglets`

Remplace les onglets affichés.

La recherche est activée par défaut. Si vous définissez `onglets`, l’embed n’affiche que les onglets que vous avez सूचीés.

* **Tapez**: `('assistant' | 'search' | 'docs')[]`

### `colorScheme`

Remplace le schéma de couleurs de l’intégration.

Lorsqu’elle est omise, l’intégration suit le CSS de l’iframe `color-scheme` , ce qui lui permet d’hériter de la préférence de la page parente ou du navigateur.

* **Tapez**: `'light' | 'dark'`

### `actions`

Boutons d’action personnalisés affichés dans la barre latérale à côté des onglets. Chaque bouton d’action déclenche un rappel lorsqu’il est cliqué.

**Remarque**: Ceci s’appelait auparavant `buttons`. Utilisez `actions` à la place.

* **Tapez**: `Array<{ icon: string, label: string, onClick: () => void }>`

### `greeting`

Message de bienvenue affiché dans l’onglet Assistant.

* **Tapez**: `{ title: string, subtitle: string }`

### `assistantName`

Remplace le nom de l’assistant affiché dans l’interface utilisateur.

* **Tapez**: `string`
* **Longueur max**: `32` caractères

### `closeButton`

Affiche un bouton de fermeture dans l’Assistant.

* **Tapez**: `boolean`

### `suggestions`

Questions suggérées affichées dans l’écran de bienvenue de l’Assistant.

* **Tapez**: `string[]`

### `trademark`

Afficher ou masquer la marque GitBook dans l’interface d’intégration — y compris le pied de page de Docs Embed et l’identité visuelle de l’Assistant.

* **Tapez**: `boolean`
* **Par défaut**: `true`

### `tools`

Outils IA personnalisés pour étendre l’Assistant. Voir [Création d’outils personnalisés](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/fr/docs-site/embedding/configuration/creating-custom-tools) pour plus de détails.

* **Tapez**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>`

### `visitor` (Accès authentifié)

Utilisé pour [Adaptive Content](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/fr/acces-au-site/adaptive-content) et [Accès authentifié](https://gitbook-v2-5hpihs24d-gitbook.vercel.app/url/gitbook.com/docs/documentation/fr/acces-au-site/authenticated-access).

* **Tapez**: `{ token?: string, unsignedClaims?: Record<string, unknown> }`

## Pièges courants

* **Ne pas encapsuler avec GitBookProvider** – L’option `GitBookFrame` nécessite 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 documentation publiée** – Assurez-vous que la prop `siteURL` correspond exactement à l’URL de votre site de documentation en production.
* **Appeler useGitBook en dehors du provider** – L’option `useGitBook` hook doit être utilisé dans un composant enfant de `GitBookProvider`.
* **Plusieurs providers dans l’arborescence** – Évitez d’imbriquer plusieurs `GitBookProvider` instances, car cela peut provoquer des conflits de contexte.
* **Utiliser d’anciens noms de composants** – Le composant est maintenant `GitBookFrame`, et non `GitBookAssistantFrame`.