Authentification

Utilisez Docs Embed avec des sites nécessitant une authentification en transmettant des jetons visiteurs ou en utilisant l’accès authentifié

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 ne 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 le jeton du visiteur directement :

Script autonome

<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>

Package NPM

Composants React

L'API de configuration de l'Embed n'a pas changé. Transmettez les jetons visiteurs signés comme visitor.token.

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

Approche 2 : Détection basée sur les cookies

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

Lorsqu'un utilisateur se connecte à vos docs authentifiés, GitBook stocke un jeton 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 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, demandez à l'utilisateur de se connecter

Script autonome

Extrait à copier-coller

Utilisez cet extrait pour charger l'intégration seulement après qu'un utilisateur se soit connecté :

<script>
  (function () {
    // Vérifier le jeton 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>

Remplacez docs.example.com par l'URL réelle de votre site de docs.

Alternative : Inviter les utilisateurs à se connecter

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

<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>

Package NPM

Composants React

Pièges courants

• Charger 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é des navigateurs. Votre application et vos docs doivent être sur le même domaine ou sous-domaine, ou transmettez le jeton directement.

• Jeton expiré – Les jetons peuvent expirer. Si l'intégration renvoie des erreurs d'authentification, demandez aux utilisateurs de se reconnecter.

• Mauvais nom de cookie utilisé – Le jeton est stocké sous la forme gitbook-visitor-token, pas gitbook-token ou d'autres variantes.

• Ne pas transmettre le jeton à init/getFrameURL – Lors de l'utilisation de 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 :

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 – Ajouter des messages de bienvenue et des actions

• Création d'outils personnalisés – Intégrer avec les API de votre produit

• Documentation Docs Embed – Guide d'intégration complet