# Référence de l’API

Docs Embed propose différentes API selon la manière dont vous l’intégrez. Cette référence couvre toutes les méthodes disponibles pour les différents modes d’intégration.

## Comparaison des méthodes

| Méthode                        | Script autonome                                              | Package NPM                      | Composants React                    |
| ------------------------------ | ------------------------------------------------------------ | -------------------------------- | ----------------------------------- |
| **Initialiser**                | `GitBook('init', options, frameOptions)`                     | `createGitBook(options)`         | `<GitBookProvider siteURL="...">`   |
| **Obtenir l’URL du cadre**     | ❌ (géré en interne)                                          | `client.getFrameURL(options)`    | `useGitBook().getFrameURL(options)` |
| **Créer un client de cadre**   | ❌ (géré en interne)                                          | `client.createFrame(iframe)`     | `useGitBook().createFrame(iframe)`  |
| **Afficher/Masquer le widget** | `GitBook('show')` / `GitBook('hide')`                        | ❌                                | ❌                                   |
| **Ouvrir/Fermer la fenêtre**   | `GitBook('open')` / `GitBook('close')` / `GitBook('toggle')` | ❌                                | ❌                                   |
| **Naviguer vers la page**      | `GitBook('navigateToPage', path)`                            | `frame.navigateToPage(path)`     | Via le client du cadre              |
| **Naviguer vers l’assistant**  | `GitBook('navigateToAssistant')`                             | `frame.navigateToAssistant()`    | Via le client du cadre              |
| **Publier un message**         | `GitBook('postUserMessage', message)`                        | `frame.postUserMessage(message)` | Via le client du cadre              |
| **Effacer le chat**            | `GitBook('clearChat')`                                       | `frame.clearChat()`              | Via le client du cadre              |
| **Configurer**                 | `GitBook('configure', settings)`                             | `frame.configure(settings)`      | Props sur `<GitBookFrame>`          |
| **Écouteurs d’événements**     | ❌                                                            | `frame.on(event, listener)`      | Via le client du cadre              |
| **Décharger**                  | `GitBook('unload')`                                          | ❌                                | ❌                                   |

## API du script autonome

### Initialisation

#### `GitBook('init', options, frameOptions)`

Initialisez le widget avec l’URL du site et un accès authentifié facultatif.

**Paramètres :**

* `options`: `{ siteURL: string }` - L’URL de votre site de documentation GitBook
* `frameOptions`: `{ visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } }` (facultatif) - Options d’accès authentifié

**Exemple :**

```javascript
window.GitBook('init', 
  { siteURL: 'https://docs.company.com' },
  { visitor: { token: 'your-jwt-token' } }
);
```

### Contrôle du widget

#### Afficher le widget

Affiche le widget GitBook s’il a été masqué.

**Exemple :**

```js
window.GitBook("show");
```

#### Masquer le widget

Masque le widget GitBook sans le décharger.

**Exemple :**

```js
window.GitBook("hide");
```

#### Ouvrir la fenêtre

Ouvre la fenêtre Docs Embed.

**Exemple :**

```js
window.GitBook("open");
```

#### Fermer la fenêtre

Ferme la fenêtre Docs Embed.

**Exemple :**

```js
window.GitBook("close");
```

#### Basculer la fenêtre

Bascule l’ouverture ou la fermeture de la fenêtre Docs Embed.

**Exemple :**

```js
window.GitBook("toggle");
```

#### Décharger le widget

Supprime complètement le widget GitBook de votre site.

**Exemple :**

```js
window.GitBook("unload");
```

### Navigation

#### `GitBook('navigateToPage', path)`

Naviguez vers une page spécifique de votre documentation GitBook par son chemin.

**Paramètres :**

* `chemin` (string) : Le chemin vers la page vers laquelle vous souhaitez naviguer

**Exemple :**

```javascript
// Naviguer vers le guide de démarrage
window.GitBook("navigateToPage", "/getting-started");

// Naviguer vers une page de documentation API spécifique
window.GitBook("navigateToPage", "/api/authentication");

// Naviguer vers la section FAQ
window.GitBook("navigateToPage", "/faq/billing");
```

#### `GitBook('navigateToAssistant')`

Naviguez directement vers l’onglet Assistant.

**Exemple :**

```javascript
// Passer à l’onglet assistant
window.GitBook("navigateToAssistant");

// Vous pourriez utiliser cela en réponse à un clic sur un bouton
document.getElementById("help-button").addEventListener("click", () => {
  window.GitBook("navigateToAssistant");
});
```

### Chat

#### `GitBook('postUserMessage', message)`

Publie un message dans le chat comme si l’utilisateur l’avait saisi.

**Paramètres :**

* `message` (string) : Le message à publier dans le chat

**Exemple :**

```javascript
// Envoyer un message prédéfini
window.GitBook("postUserMessage", "How do I reset my password?");

// Envoyer un message en fonction de l’action de l’utilisateur
function askAboutBilling() {
  window.GitBook("postUserMessage", "I have questions about my billing");
}

// Envoyer un message avec contexte
const userPlan = "premium";
window.GitBook(
  "postUserMessage",
  `Je suis sur le forfait ${userPlan} et j’ai besoin d’aide pour des fonctionnalités avancées`
);
```

#### `GitBook('clearChat')`

Efface tous les messages de la session de chat actuelle.

**Exemple :**

```javascript
// Effacer le chat
window.GitBook("clearChat");

// Effacer le chat et démarrer une nouvelle conversation
function startNewConversation() {
  window.GitBook("clearChat");
  window.GitBook("postUserMessage", "Hello, I need help with a new issue");
}

// Effacer le chat lors du changement de contexte
document.getElementById("new-topic").addEventListener("click", () => {
  window.GitBook("clearChat");
  window.GitBook("navigateToAssistant");
});
```

### Configuration

#### `GitBook('configure', settings)`

Configurez l’intégration avec des options de personnalisation. Consultez la [section Configuration](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/fr/publishing-documentation/implementation/script#configuration-options) pour connaître les options disponibles.

**Exemple :**

```javascript
window.GitBook('configure', {
  trademark: false,
  tabs: ['assistant', 'docs'],
  actions: [
    {
      icon: 'circle-question',
      label: 'Contacter le support',
      onClick: () => window.open('https://support.example.com', '_blank')
    }
  ],
  greeting: { title: 'Bienvenue !', subtitle: 'Comment puis-je aider ?' },
  suggestions: ['Qu’est-ce que GitBook ?', 'Comment démarrer ?']
});
```

## API du package NPM

### Fabrique de client

#### `createGitBook(options)`

Crée une instance de client GitBook.

**Paramètres :**

* `options`: `{ siteURL: string }` - L’URL de votre site de documentation GitBook

**Renvoie :** `GitBookClient`

**Exemple :**

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

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

#### `client.getFrameURL(options)`

Obtenez l’URL de l’iframe avec un accès authentifié facultatif.

**Paramètres :**

* `options`: `{ visitor?: { token?: string, unsignedClaims?: Record<string, unknown> } }` (facultatif)

**Renvoie :** `string`

**Exemple :**

```javascript
const iframeURL = gitbook.getFrameURL({
  visitor: {
    token: 'your-jwt-token',
    unsignedClaims: { userId: '123', plan: 'premium' }
  }
});
```

#### `client.createFrame(iframe)`

Crée un client de cadre pour communiquer avec l’iframe.

**Paramètres :**

* `iframe`: `HTMLIFrameElement` - L’élément iframe

**Renvoie :** `GitBookFrameClient`

**Exemple :**

```javascript
const iframe = document.createElement('iframe');
iframe.src = gitbook.getFrameURL();
const frame = gitbook.createFrame(iframe);
```

### Méthodes du client de cadre

#### `frame.navigateToPage(path)`

Naviguez vers une page spécifique dans l’onglet de documentation.

**Paramètres :**

* `chemin`: `string` - Le chemin vers la page

#### `frame.navigateToAssistant()`

Passez à l’onglet assistant.

#### `frame.postUserMessage(message)`

Publie un message dans le chat.

**Paramètres :**

* `message`: `string` - Le message à publier

#### `frame.clearChat()`

Efface l’historique du chat.

#### `frame.configure(settings)`

Configurez l’intégration. Consultez la [section Configuration](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/fr/publishing-documentation/implementation/nodejs#configuration-options) pour connaître les options disponibles.

#### `frame.on(event, listener)`

Enregistre un écouteur d’événement.

**Paramètres :**

* `event`: `string` - Le nom de l’événement
* `listener`: `Function` - La fonction de rappel

**Renvoie :** `() => void` - Fonction de désabonnement

**Exemple :**

```javascript
const unsubscribe = frame.on('close', () => {
  console.log('Frame closed');
});

// Plus tard, se désabonner
unsubscribe();
```

## API des composants React

Consultez le [guide d’intégration React](https://gitbook-open-v2-preview.gitbook.workers.dev/url/gitbook.com/docs/documentation/fr/publishing-documentation/embedding/implementation/react) pour les props des composants et le `useGitBook` API du hook.