身份验证

通过传递访客令牌或使用已验证访问，在需要身份验证的网站上使用 Docs Embed

如果你的 GitBook 文档需要身份验证（例如通过 OIDC、Auth0 或自定义后端进行访客身份验证），则除非提供用户的身份验证令牌，否则嵌入内容无法访问你的文档内容。

有两种方法：

1. 直接传递令牌 （推荐）- 使用访客令牌初始化嵌入

2. 使用基于 Cookie 的检测 - 在加载前检查 Cookie 中是否存在令牌

方法 1：直接传递令牌（推荐）

初始化嵌入时，直接传递访客令牌：

独立脚本

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

NPM 包

React 组件

Embed 配置 API 没有变化。将已签名的访客令牌传递为 visitor.token.

对于已认证站点，GitBook 会将此令牌转发给站点，形式为 jwt_token ，位于 iframe/script URL 中。如果你从已认证站点加载独立脚本，则必须在 jwt_token 后，在 <script src> URL 中包含它。

方法 2：基于 Cookie 的检测

如果你的文档站点将访客令牌存储在 Cookie 中（如 gitbook-visitor-token），则你可以在加载嵌入之前检查它。

当用户登录到你的已认证文档时，GitBook 会将访客令牌存储到其浏览器 Cookie 中，键名为 gitbook-visitor-token。嵌入需要此令牌才能从你的文档中获取内容。

流程如下：

1. 用户登录到你的文档站点

2. GitBook 将访客令牌存储到浏览器 Cookie 中

3. 你的应用检查令牌

4. 如果令牌存在，则加载嵌入并传递令牌

5. 如果令牌不存在，则提示用户登录

独立脚本

复制粘贴片段

使用此代码片段，在用户登录后才加载嵌入：

<script>
  (function () {
    // 检查 Cookie 中的访客令牌
    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] 请先登录你的文档。");
      return;
    }

    // 令牌存在，加载嵌入
    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>

替换 docs.example.com 替换为你实际的文档站点 URL。

替代方案：提示用户登录

如果令牌缺失，你可以提示用户登录：

<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) {
      // 重定向到文档或显示一条消息
      alert("请先登录你的文档以访问帮助内容。");
      window.location.href = "https://docs.example.com";
      return;
    }

    // 使用令牌加载嵌入
    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>

NPM 包

React 组件

常见问题

• 在登录前加载嵌入 – 始终在加载脚本或组件前检查令牌，或者在初始化时直接传递令牌。

• 令牌未在跨域间持久化 – 由于浏览器安全策略，Cookie 不会在不同域之间持久化。你的应用和文档必须位于同一域或子域下，或者直接传递令牌。

• 令牌已过期 – 令牌可能会过期。如果嵌入返回身份验证错误，请提示用户重新登录。

• 使用了错误的 Cookie 名称 – 令牌存储为 gitbook-visitor-token，而不是 gitbook-token 或其他变体。

• 未将令牌传递给 init/getFrameURL – 使用基于 Cookie 的方法时，确保将令牌传递给 GitBook('init', ..., { visitor: { token } }) 或者 getFrameURL({ visitor: { token } }).

调试

要验证令牌是否存在，请打开浏览器控制台并运行：

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

如果这返回 undefined，说明用户尚未登录你的文档。

后续步骤

• 自定义嵌入 – 添加欢迎消息和操作

• 创建自定义工具 – 与你的产品 API 集成

• Docs Embed 文档 – 完整嵌入指南