> 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/publier/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 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 %}
**Installer le paquet**

Ajoutez `@gitbook/embed` dans 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 paquet**

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 paquet NPM vous laisse la configuration de l'iframe. L'implémentation autonome [balise de script](/docs/documentation/fr/publier/embedding/implementation/script.md) l'ajoute 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("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: 'Support Copilot',
  closeButton: true,
  suggestions: ['What is GitBook?', 'How do I get started?'],
  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é');
});

// Désabonnez-vous une fois terminé
const unsubscribe = frame.on('navigate', (data) => {
  console.log('Navigated to:', data.path);
});
```

{% endstep %}
{% endstepper %}

## Référence de l'API

### Fabrique de client

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

### Méthodes du client du cadre

* `frame.navigateToPage(path: string)` → `void` - Naviguer vers une page spécifique dans l'onglet Docs
* `frame.navigateToAssistant()` → `void` - Basculer vers l'onglet Assistant
* `frame.postUserMessage(message: string)` → `void` - Publier 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énements (renvoie une fonction de désabonnement)

## Options de configuration

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

#### `tabs`

Remplacez les onglets affichés.

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

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

#### `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**: C'était auparavant appelé `boutons`. Utilisez `actions` à la place.

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

#### `message d'accueil`

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 maximale**: `32` caractères

#### `closeButton`

Affichez un bouton de fermeture dans l'Assistant.

* **Type**: `booléen`

#### `suggestions`

Questions suggérées affichées dans l'écran d'accueil 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 la marque de l'Assistant.

* **Type**: `booléen`
* **Par défaut**: `vrai`

#### `outils`

Outils IA personnalisés pour étendre l'Assistant. Voir [Créer des outils personnalisés](/docs/documentation/fr/publier/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`

Remplacez le jeu 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'`

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

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

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

## Pièges courants

* **Oublier d'installer le paquet** – Exécutez `npm install @gitbook/embed` avant d'importer.
* **siteURL manquant** – L' `siteURL` option est obligatoire et doit correspondre à votre site de documentation publié.
* **L'iframe ne s'affiche pas** – Assurez-vous que le conteneur parent a 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.
* **Utilisation d'anciennes méthodes de l'API** – Les méthodes telles que `open()`, `close()`, `toggle()`, et `destroy()` ne sont pas disponibles dans le paquet NPM. Utilisez plutôt les méthodes du client de 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/publier/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.