# Authentification

Si votre documentation GitBook nécessite une authentification (par ex. authentification des visiteurs via OIDC, Auth0 ou un backend personnalisé), l’intégration ne peut pas accéder au contenu de vos docs à moins que le jeton d’authentification de l’utilisateur soit fourni.

Il existe deux approches :

1. **Transmettre le jeton directement** (recommandé) - Initialiser l’intégration avec le jeton du visiteur
2. **Utiliser la détection basée sur les cookies** - Vérifier la présence du jeton dans les cookies avant le chargement

## Approche 1 : transmettre le jeton directement (recommandé)

Lors de l’initialisation de l’intégration, transmettez directement le jeton du visiteur :

{% tabs %}
{% tab title="Script autonome" %}

```html
<script src="https://docs.company.com/~gitbook/embed/script.js?jwt_token=your-jwt-token"></script>
<script>
  window.GitBook(
    "init",
    { siteURL: "https://docs.company.com" },
    { visitor: { token: "your-jwt-token" } }
  );
  window.GitBook("show");
</script>
```

{% endtab %}

{% tab title="Package NPM" %}

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

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

const iframe = document.createElement("iframe");
iframe.src = gitbook.getFrameURL({
  visitor: {
    token: "your-jwt-token",
    unsignedClaims: { userId: "123", plan: "premium" },
  },
});
```

{% endtab %}

{% tab title="Composants React" %}

```jsx
<GitBookProvider siteURL="https://docs.company.com">
  <GitBookFrame
    visitor={{
      token: "your-jwt-token",
      unsignedClaims: { userId: "123" },
    }}
  />
</GitBookProvider>
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
L’API de configuration de l’Embed n’a pas changé. Transmettez les jetons visiteur signés en tant que `visitor.token`.

Pour les sites authentifiés, GitBook transmet ce jeton au site sous la forme de `jwt_token` dans l’URL de l’iframe/du script. Si vous chargez le script autonome depuis un site authentifié, vous devez inclure `jwt_token` dans l’URL `<script src>` .
{% endhint %}

## Approche 2 : détection basée sur les cookies

Si votre site de docs stocke le jeton du visiteur dans les cookies (comme `gitbook-visitor-token`), vous pouvez vérifier sa présence avant de charger l’intégration.

Lorsqu’un utilisateur se connecte à vos docs authentifiées, GitBook stocke un jeton de visiteur dans les cookies de son navigateur sous la clé `gitbook-visitor-token`. L’intégration a besoin de ce jeton pour récupérer le contenu de vos docs.

**Le flux :**

1. L’utilisateur se connecte à votre site de docs
2. GitBook stocke le jeton du visiteur dans les cookies du navigateur
3. Votre application vérifie la présence du jeton
4. Si le jeton existe, chargez l’intégration et transmettez le jeton
5. Si le jeton n’existe pas, invitez l’utilisateur à se connecter

{% tabs %}
{% tab title="Script autonome" %}
**Extrait à copier-coller**

Utilisez cet extrait pour charger l’intégration uniquement après qu’un utilisateur s’est connecté :

```html
<script>
  (function () {
    // Vérifier la présence du jeton du visiteur dans les cookies
    function getCookie(name) {
      var value = "; " + document.cookie;
      var parts = value.split("; " + name + "=");
      if (parts.length === 2) return parts.pop().split(";").shift();
    }

    var token = getCookie("gitbook-visitor-token");

    if (!token) {
      console.warn("[Docs Embed] Veuillez d’abord vous connecter à vos docs.");
      return;
    }

    // Le jeton existe, charger l’intégration
    var script = document.createElement("script");
    script.src =
      "https://docs.example.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    script.async = true;
    script.onload = function () {
      window.GitBook(
        "init",
        { siteURL: "https://docs.example.com" },
        { visitor: { token: token } }
      );
      window.GitBook("show");
    };
    document.head.appendChild(script);
  })();
</script>
```

{% hint style="warning" %}
Remplacez `docs.example.com` par l’URL réelle de votre site de docs.
{% endhint %}

**Alternative : inviter les utilisateurs à se connecter**

Si le jeton est absent, vous pouvez inviter les utilisateurs à se connecter :

```html
<script>
  (function () {
    function getCookie(name) {
      var value = "; " + document.cookie;
      var parts = value.split("; " + name + "=");
      if (parts.length === 2) return parts.pop().split(";").shift();
    }

    var token = getCookie("gitbook-visitor-token");

    if (!token) {
      // Rediriger vers les docs ou afficher un message
      alert("Veuillez vous connecter à vos docs pour accéder à l’aide.");
      window.location.href = "https://docs.example.com";
      return;
    }

    // Charger l’intégration avec le jeton
    var script = document.createElement("script");
    script.src =
      "https://docs.example.com/~gitbook/embed/script.js?jwt_token=" +
      encodeURIComponent(token);
    script.async = true;
    script.onload = function () {
      window.GitBook(
        "init",
        { siteURL: "https://docs.example.com" },
        { visitor: { token: token } }
      );
      window.GitBook("show");
    };
    document.head.appendChild(script);
  })();
</script>
```

{% endtab %}

{% tab title="Package NPM" %}
Lorsque vous utilisez le package NPM, vérifiez la présence du jeton avant l’initialisation :

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

function initializeEmbed() {
  // Vérifier la présence du jeton dans les cookies
  const getCookie = (name) => {
    const value = `; ${document.cookie}`;
    const parts = value.split(`; ${name}=`);
    if (parts.length === 2) return parts.pop().split(";").shift();
  };

  const token = getCookie("gitbook-visitor-token");

  if (!token) {
    console.warn("[Docs Embed] L’utilisateur doit d’abord se connecter.");
    return null;
  }

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

  const iframe = document.createElement("iframe");
  iframe.src = gitbook.getFrameURL({
    visitor: { token: token },
  });
  const frame = gitbook.createFrame(iframe);

  document.getElementById("embed-container").appendChild(iframe);
  return frame;
}

initializeEmbed();
```

{% endtab %}

{% tab title="Composants React" %}
Pour les applications React, affichez l’intégration de manière conditionnelle en fonction de la présence du jeton :

```jsx
import { useEffect, useState } from "react";
import { GitBookProvider, GitBookFrame } from "@gitbook/embed/react";

function App() {
  const [token, setToken] = useState(null);

  useEffect(() => {
    // Vérifier la présence du jeton dans les cookies
    const getCookie = (name) => {
      const value = `; ${document.cookie}`;
      const parts = value.split(`; ${name}=`);
      if (parts.length === 2) return parts.pop().split(";").shift();
    };

    const visitorToken = getCookie("gitbook-visitor-token");
    setToken(visitorToken);
  }, []);

  if (!token) {
    return (
      <div>
        <p>Veuillez vous connecter pour accéder à l’aide.</p>
        <a href="https://docs.example.com">Se connecter</a>
      </div>
    );
  }

  return (
    <GitBookProvider siteURL="https://docs.example.com">
      <YourAppContent />
      <GitBookFrame visitor={{ token: token }} />
    </GitBookProvider>
  );
}
```

{% endtab %}
{% endtabs %}

## Pièges courants

* **Chargement de l’intégration avant la connexion** – Vérifiez toujours la présence du jeton avant de charger le script ou les composants, ou transmettez le jeton directement lors de l’initialisation.
* **Le jeton ne persiste pas entre les domaines** – Les cookies ne persistent pas entre différents domaines en raison des politiques de sécurité du navigateur. Votre application et vos docs doivent être sur le même domaine ou sous-domaine, ou bien transmettez le jeton directement.
* **Jeton expiré** – Les jetons peuvent expirer. Si l’intégration renvoie des erreurs d’authentification, invitez les utilisateurs à se reconnecter.
* **Utilisation d’un mauvais nom de cookie** – Le jeton est stocké sous `gitbook-visitor-token`, et non sous `gitbook-token` ou d’autres variantes.
* **Ne pas transmettre le jeton à init/getFrameURL** – Lorsque vous utilisez l’approche basée sur les cookies, assurez-vous de transmettre le jeton à `GitBook('init', ..., { visitor: { token } })` ou `getFrameURL({ visitor: { token } })`.

## Débogage

Pour vérifier que le jeton est présent, ouvrez la console de votre navigateur et exécutez :

```javascript
document.cookie.split(";").find((c) => c.includes("gitbook-visitor-token"));
```

Si cela renvoie `undefined`, l’utilisateur ne s’est pas encore connecté à vos docs.

## Étapes suivantes

* [Personnalisation de l’Embed](/docs/documentation/fr/docs-site/embedding/configuration/customizing-docs-embed.md) – Ajouter des messages de bienvenue et des actions
* [Création d’outils personnalisés](/docs/documentation/fr/docs-site/embedding/configuration/creating-custom-tools.md) – Intégrer vos API produit
* [Documentation Docs Embed](/docs/documentation/fr/docs-site/embedding.md) – Guide complet d’intégration


---

# Agent Instructions: 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:

```
GET https://gitbook.com/docs/documentation/fr/docs-site/embedding/using-with-authenticated-docs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.