身份验证

通过传递访客令牌或使用已验证访问，在需要身份验证的站点中使用 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 文档 – 完整的嵌入指南