> 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/publish/embedding/implementation/nodejs.md).

# Node.js/NPM

Intégrez Docs Embed à l’aide du package NPM pour un contrôle complet au niveau de l’application

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

## Étapes

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

Ajoutez `@gitbook/embed` à votre projet :

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

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

{% step %}
**Importer le paquet**

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

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

Ou en 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', // Optionnel : pour Adaptive Content 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. L’implémentation autonome avec la [balise Script](https://gitbook.com/docs/documentation/fr/publish/embedding/implementation/script.md) ajoute ce paramètre automatiquement.
{% endhint %}
{% endstep %}

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

Créez une instance de cadre GitBook et intégrez-la à votre page :

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

{% endstep %}

{% step %}
**Contrôler l'intégration par programmation**

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("Comment puis-je commencer ?");

// 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 de 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éagir 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` - Récupérer l’URL de l’iframe avec des options facultatives
* `client.createFrame(iframe: HTMLIFrameElement)` → `GitBookFrameClient` - Créer un client de frame pour communiquer avec l’iframe

### Méthodes du client de cadre

* `frame.navigateToPage(path: string)` → `void` - Accéder à une page spécifique dans l’onglet de documentation
* `frame.navigateToAssistant()` → `void` - Passer à l’onglet Assistant
* `frame.postUserMessage(message: string)` → `void` - Envoyer un message dans le chat
* `frame.clearChat()` → `void` - Effacer l’historique du chat
* `frame.configure(settings: Partial<GitBookEmbeddableConfiguration>)` → `void` - Configurer l’intégration
* `frame.on(event: string, listener: Function)` → `() => void` - Enregistrer un écouteur d’événement (renvoie une fonction de désabonnement)

## Options de configuration

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

#### `tabs`

Remplace les onglets affichés.

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

* **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é.

**Remarque** : ce paramètre s’appelait auparavant `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 }`

#### `assistantName`

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

* **Type**: `string`
* **Longueur maximale**: `32` caractères

#### `closeButton`

Afficher un bouton de fermeture dans l’Assistant.

* **Type**: `boolean`

#### `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 d’intégration — y compris le pied de page de Docs Embed et l’image de marque de l’Assistant.

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

#### `tools`

Outils d’IA personnalisés pour étendre l’assistant. Consultez [Créer des outils personnalisés](https://gitbook.com/docs/documentation/fr/publish/embedding/configuration/creating-custom-tools.md) pour plus de détails.

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

### Options de l'URL du cadre

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

#### `colorScheme`

Remplace le jeu de couleurs de l’intégration.

Si cette option est omise, l’intégration suit la propriété CSS `color-scheme`, ce qui lui permet d’hériter des préférences de la page parente ou du navigateur.

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

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

Transmettez à `getFrameURL({ visitor: {...} })`. Utilisé pour le [contenu adaptatif](https://gitbook.com/docs/documentation/fr/publish/adaptive-content.md) et [Accès authentifié](https://gitbook.com/docs/documentation/fr/publish/site-audience/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 l’importation.
* **siteURL manquant** – L’option `siteURL` est obligatoire et doit correspondre à l’URL de votre site de documentation publié.
* **L’iframe ne s’affiche pas** – Vérifiez que le conteneur parent est suffisamment large et haut pour afficher l’iframe.
* **Méthodes du frame appelées avant l’initialisation** – Attendez que `createFrame()` soit terminée avant d’appeler les méthodes du frame.
* **Oubli de la désinscription des événements** – Pensez à appeler la fonction de désinscription renvoyée par `frame.on()` pour éviter les fuites de mémoire.
* **Utilisation 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 frame.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
