# 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 de la compilation ou la gestion personnalisée d’iframes.

## Étapes

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

Ajoutez `@gitbook/embed` dans votre projet :

```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 le package**

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

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

Ou en utilisant CommonJS :

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

{% endstep %}

{% step %}
**Initialisez 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éez 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";
```

{% endstep %}

{% step %}
**Attachez 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ôlez 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();

// Envoyer un message au chat
frame.postUserMessage("How do I get started?");

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

{% endstep %}

{% step %}
**Configurez 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: 'Contact Support',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'Welcome!', subtitle: 'How can I help?' },
  assistantName: 'Support Copilot',
  closeButton: true,
  suggestions: ['What is GitBook?', 'How do I get started?'],
  tools: [/* ... */]
});
```

{% endstep %}

{% step %}
**Écoutez 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('Frame closed');
});

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

{% endstep %}
{% endstepper %}

## Référence de l’API

### Usine 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 de 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` - Envoyer un message au 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({...})`.

#### `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')[]`

#### `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?: {...} }>`

### Options d’URL du cadre

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

#### `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'`

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

À transmettre à `getFrameURL({ visitor: {...} })`. 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

* **Oublier d’installer le package** – Exécutez `npm install @gitbook/embed` avant l’import.
* **siteURL manquant** – L’option `siteURL` est requise et doit correspondre à votre site de documentation publié.
* **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()` se termine avant d’appeler les méthodes du cadre.
* **Ne pas se désabonner des événements** – Pensez à 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** – Des méthodes comme `open()`, `close()`, `toggle()`, et `destroy()` ne sont pas disponibles dans le package NPM. Utilisez plutôt les méthodes du client de cadre.