> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/fr/docs-site/embedding/implementation/nodejs.md).

# Node.js/NPM

Si vous avez besoin de plus de contrôle et souhaitez travailler au niveau de l’application, vous pouvez installer le package d’intégration GitBook depuis npm. Cette approche est idéale pour le rendu côté serveur, l’intégration au moment du build ou la gestion personnalisée des iframes.

## Étapes

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

Ajouter `@gitbook/embed` à votre projet :

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

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

{% step %}
**Importer le package**

Dans le code de votre application, importez la `createGitBook` fonction :

```javascript
import { createGitBook } from "@gitbook/embed";
```

Ou en utilisant CommonJS :

```javascript
const { createGitBook } = require("@gitbook/embed");
```

{% endstep %}

{% step %}
**Initialiser GitBook**

Créez une instance GitBook avec l’URL de votre site de documentation :

```javascript
const gitbook = createGitBook({
  siteURL: "https://docs.company.com",
});
```

{% endstep %}

{% step %}
**Créer une iframe**

Générez un élément iframe et définissez sa source sur l’URL d’intégration :

```javascript
const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token', // Facultatif : pour le contenu adaptatif ou l’accès authentifié
    unsignedClaims: { // Facultatif : revendications personnalisées pour les expressions dynamiques
      userId: '123',
      plan: 'premium'
    }
  }
});
iframe.id = "gitbook-embed-container";
iframe.style.border = "none";
iframe.style.width = "100%";
iframe.style.height = "600px";
iframe.allow = "clipboard-write";
```

{% hint style="info" %}
Si vous utilisez l’onglet Assistant, définissez `allow="clipboard-write"` sur l’iframe. Le package NPM vous laisse configurer l’iframe. La version autonome [balise script](/docs/documentation/fr/docs-site/embedding/implementation/script.md) l’ajoute automatiquement.
{% endhint %}
{% endstep %}

{% step %}
**Attacher le cadre**

Créez une instance de cadre GitBook et montez-la sur votre page :

```javascript
const frame = gitbook.createFrame(iframe);
document.getElementById("gitbook-embed-container").appendChild(iframe);
```

{% endstep %}

{% step %}
**Contrôler l’intégration par programme**

Utilisez l’instance du cadre pour interagir avec l’intégration :

```javascript
// Naviguer vers une page spécifique dans l’onglet Docs
frame.navigateToPage("/getting-started");

// Passer à l’onglet Assistant
frame.navigateToAssistant();

// Publier un message dans le chat
frame.postUserMessage("How do I get started?");

// Effacer l’historique du chat
frame.clearChat();
```

{% endstep %}

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

Configurez l’intégration avec des options de personnalisation :

```javascript
frame.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 du support',
  closeButton: true,
  suggestions: ['Qu’est-ce que GitBook ?', 'Comment puis-je commencer ?'],
  tools: [/* ... */]
});
```

{% endstep %}

{% step %}
**Écouter les événements**

Enregistrez des écouteurs d’événements pour répondre aux événements de l’intégration :

```javascript
frame.on('close', () => {
  console.log('Cadre fermé');
});

// Se désabonner une fois terminé
const unsubscribe = frame.on('navigate', (data) => {
  console.log('Navigué vers :', data.path);
});
```

{% endstep %}
{% endstepper %}

## Référence de l’API

### Fabrique du client

* `createGitBook(options: { siteURL: string })` → `GitBookClient`
* `client.getFrameURL(options?: { visitor?: {...}, colorScheme?: 'light' | 'dark' })` → `string` - Obtenez l’URL de l’iframe avec des options de cadre facultatives
* `client.createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient` - Créez un client de cadre pour communiquer avec l’iframe

### Méthodes du client de cadre

* `frame.navigateToPage(path: string)` → `void` - Naviguez vers une page spécifique dans l’onglet Docs
* `frame.navigateToAssistant()` → `void` - Passez à l’onglet Assistant
* `frame.postUserMessage(message: string)` → `void` - Publiez un message dans le chat
* `frame.clearChat()` → `void` - Effacez l’historique du chat
* `frame.configure(settings: Partial<GitBookEmbeddableConfiguration>)` → `void` - Configurez l’intégration
* `frame.on(event: string, listener: Function)` → `() => void` - Enregistrez un écouteur d’événements (renvoie une fonction de désabonnement)

## Options de configuration

La plupart des options de personnalisation sont disponibles via `frame.configure({...})`.

#### `onglets`

Remplacez les onglets affichés.

La recherche est activée par défaut. Si vous définissez `onglets`, l’intégration n’affiche que les onglets que vous listez.

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

#### `actions`

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

**Note**: Cela s’appelait auparavant `boutons`. Utilisez `actions` à la place.

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

#### `message de bienvenue`

Message de bienvenue affiché dans l’onglet Assistant.

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

#### `assistantName`

Remplacez le nom de l’assistant affiché dans l’interface.

* **Type**: `string`
* **Longueur max.**: `32` caractères

#### `bouton de fermeture`

Affichez un bouton de fermeture dans l’Assistant.

* **Type**: `boolean`

#### `suggestions`

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

* **Type**: `string[]`

#### `marque`

Affichez ou masquez la marque GitBook dans l’interface d’intégration, y compris le pied de page de l’intégration Docs et l’image de marque de l’Assistant.

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

#### `outils`

Outils d’IA personnalisés pour étendre l’Assistant. Voir [Créer des outils personnalisés](/docs/documentation/fr/docs-site/embedding/configuration/creating-custom-tools.md) pour plus de détails.

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

### Options d’URL du cadre

Certaines options sont transmises à `getFrameURL({...})`.

#### `schéma de couleurs`

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

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

* **Type**: `'light' | 'dark'`

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

Transmettez à `getFrameURL({ visitor: {...} })`. Utilisé pour [Contenu adaptatif](/docs/documentation/fr/acces-au-site/adaptive-content.md) et [Accès authentifié](/docs/documentation/fr/acces-au-site/authenticated-access.md).

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

## Pièges courants

* **Oublier d’installer le package** – Exécutez `npm install @gitbook/embed` avant d’importer.
* **siteURL manquant** – L’option `siteURL` est requise et doit correspondre à votre site de documentation publié.
* **L’iframe ne s’affiche pas** – Assurez-vous que le conteneur parent dispose d’une largeur/hauteur suffisante pour afficher l’iframe.
* **Méthodes du cadre appelées avant l’initialisation** – Attendez que `createFrame()` soit terminé avant d’appeler les méthodes du cadre.
* **Ne pas se désabonner des événements** – N’oubliez pas d’appeler la fonction de désabonnement renvoyée par `frame.on()` pour éviter les fuites de mémoire.
* **Utiliser d’anciennes méthodes de l’API** – Les méthodes telles que `open()`, `close()`, `toggle()`, et `destroy()` ne sont pas disponibles dans le package NPM. Utilisez plutôt les méthodes du client du cadre.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://gitbook.com/docs/documentation/fr/docs-site/embedding/implementation/nodejs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.