身份验证

通过传递访客令牌或使用已验证访问方式，在需要身份验证的网站上使用文档嵌入

如果您的 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 文档 – 完整的嵌入指南