认证

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

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

有两种方法：

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

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

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

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

独立脚本

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

NPM 包

React 组件

方法二：基于 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";
    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";
    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 文档 – 完整的嵌入指南