脚本标签

了解如何使用单个脚本标签将 Docs Embed 小部件添加到任何网站或 Web 应用

将 GitBook Assistant 嵌入到您的网站或应用程序的最简单集成方法是将一个独立脚本包含到您的 HTML 中。每个 GitBook 文档站点都提供一个现成的嵌入脚本，该脚本会自动加载小部件并将其连接到您的文档。本页说明如何操作。

不需要 SDK、构建步骤或框架集成。只需包含脚本，小部件便会显示在您的页面上。

开始使用

复制您的嵌入脚本 URL

在 GitBook 应用中导航到您的文档站点，转到设置选项卡，然后到 AI 与 MCP 并复制嵌入脚本 URL。

您也可以手动构建：

https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js

将您的 YOUR_DOCS_DOMAIN 替换为您真实文档站点的域名。

将脚本添加到您的 HTML

在页面 HTML 中添加以下标签。将其放在 <head> 或直接放在 </body>.

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>window.GitBook('show');</script>

如果您的文档需要身份验证

如果您的文档位于身份验证后面，脚本必须包含一个签名的 JWT 令牌。

将其作为查询参数追加：

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js?jwt_token=YOUR_TOKEN"></script>

验证

重新加载您的页面。

小部件应出现在右下角。

可选地配置嵌入

您可以在显示前自定义小部件。加载脚本后并在调用 configure 之前调用 window.GitBook('show').

<script src="https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js"></script>
<script>
  window.GitBook('configure', {
    button: {
      label: 'Ask',
      icon: 'assistant' // assistant | sparkle | help | book
    },
    trademark: false,
    tabs: ['assistant', 'docs'],
    actions: [
      {
        icon: 'circle-question',
        label: 'Contact support',
        onClick: () => window.open('https://support.example.com', '_blank')
      }
    ],
    greeting: {
      title: 'Welcome',
      subtitle: 'How can I help?'
    },
    suggestions: [
      'What is GitBook?',
      'How do I get started?'
    ]
  });

  window.GitBook('show');
</script>

使用此方法，您可以自定义：

按钮标签和图标
小部件内可见的选项卡
自定义操作按钮
欢迎标题和副标题
向用户显示的建议提示。

控制小部件可见性

您可以通过 API 在运行时控制可见性和状态。

<script>
  // 使小部件可见
  window.GitBook('show');

  // 从页面中移除小部件
  window.GitBook('hide');

  // 打开小部件面板
  window.GitBook('open');

  // 关闭小部件面板
  window.GitBook('close');

  // 切换打开或关闭状态
  window.GitBook('toggle');
</script>

当您希望将小部件连接到您自己的 UI 触发器时，这很有用。

以编程方式导航和交互

您可以从代码驱动小部件以进行导航、切换选项卡或发送消息。

<script>
  // 在小部件内打开特定的文档页面
  window.GitBook('navigateToPage', '/getting-started');

  // 切换到助手选项卡
  window.GitBook('navigateToAssistant');

  // 向助手发送用户消息
  window.GitBook('postUserMessage', 'How do I get started?');

  // 清除当前聊天记录
  window.GitBook('clearChat');
</script>

此功能的典型用途包括：

从您的应用向文档页面添加深度链接
预填充一个问题
在流程之间重置对话

动态加载嵌入脚本

如果您只想有条件地加载小部件，或需要在运行时附加身份验证令牌，请以编程方式注入脚本。

<script>
  function loadGitBookEmbed() {
    var token = "" // 如果您的站点需要身份验证，请用您的 JWT 令牌填充
    var script = document.createElement('script');
    script.src = 'https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js'
      + token ? '?jwt_token=' + encodeURIComponent(token) : ';
    script.async = true;
    script.onload = function () {
      window.GitBook('show');
    };
    document.head.appendChild(script);
  }

  loadGitBookEmbed();
</script>

当小部件应仅在用户操作或功能标志之后加载时，请使用此模式

API 参考

初始化

GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} }) - 使用站点 URL 初始化小部件并可选地启用认证访问

小部件控制

GitBook('show') - 显示小部件按钮
GitBook('hide') - 隐藏小部件按钮
GitBook('open') - 打开小部件窗口
GitBook('close') - 关闭小部件窗口
GitBook('toggle') - 切换小部件窗口

聊天

GitBook('postUserMessage', message: string) - 向聊天发送一条消息
GitBook('clearChat') - 清除聊天记录

配置

GitBook('configure', settings: {...}) - 配置小部件设置（见下面的“配置”部分）
GitBook('unload') - 完全从页面移除小部件

配置选项

配置选项可通过 GitBook('configure', {...}):

`tabs`

覆盖要显示的选项卡。默认使用您站点的配置。

类型: ('assistant' | 'docs')[]
选项:
- ['assistant', 'docs'] - 显示两个选项卡
- ['assistant'] - 仅显示助手选项卡
- ['docs'] - 仅显示文档选项卡

`actions`

在侧边栏与选项卡并列呈现的自定义操作按钮。每个操作按钮在被点击时会触发回调。

注意：此项之前被命名为 buttons。请使用 actions 来代替。

类型: Array<{ icon: string, label: string, onClick: () => void }>
属性:
- icon: string - 图标名称。任何 FontAwesome 图标均受支持
- label: string - 按钮标签文本
- onClick: () => void | Promise<void> - 点击时的回调函数

`greeting`

在助手选项卡中显示的欢迎消息。

类型: { title: string, subtitle: string }

`suggestions`

在助手欢迎界面中显示的建议问题。

类型: string[]

`trademark`

在嵌入 UI 中显示或隐藏 GitBook 商标 —— 包括文档嵌入页脚和助手品牌标识。

类型: boolean
默认: true
示例:

window.GitBook('configure', {
  trademark: false
});

`tools`

自定义 AI 工具以扩展助手。详情见创建自定义工具部分。

类型: Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>

`button`

配置用于启动嵌入的小部件按钮（仅适用于独立脚本）。这允许您自定义出现在页面右下角的按钮的标签和图标。

类型: { label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }
属性:
- label: string - 按钮上显示的文本
- icon: 'assistant' | 'sparkle' | 'help' | 'book' - 按钮上显示的图标
  - assistant - 助手图标
  - sparkle - 闪光图标
  - help - 帮助/问号图标
  - book - 书本图标

示例：

window.GitBook('configure', {
  button: {
    label: 'Ask',
    icon: 'assistant'
  }
});

注意： 此选项仅在使用独立脚本标签实现时可用。对于 React 或 Node.js 实现，您需要创建自己的按钮来触发嵌入。

`visitor` （已认证访问）

在使用以下方式初始化时传递 GitBook('init', options, frameOptions)。用于自适应内容和已认证访问.

类型: { token?: string, unsignedClaims?: Record<string, unknown> }
属性:
- token: string （可选）- 签名的 JWT 令牌
- unsignedClaims: Record<string, unknown> （可选）- 用于动态表达式的未签名声明

常见陷阱

脚本 URL 不正确 – 确保您使用的是实际的文档 URL，而不是示例 docs.company.com.
在脚本加载前调用 GitBook – 将 API 调用包装在 script.onload 或将它们放在脚本标签之后。
已认证的文档无法访问 – 如果您的文档需要登录，初始化时必须提供 visitor.token 。参见在已认证文档中使用.
CORS 或 CSP 错误 – 确保您站点的内容安全策略允许从您的 GitBook 域加载脚本和 iframe。
小部件不可见 – 检查页面上与其他元素的 z-index 冲突。小部件默认使用较高的 z-index。
忘记初始化 – 确保在使用其他方法之前调用 GitBook('init', { siteURL: '...' }) 。

最后更新于18小时前

这有帮助吗？

早上好

hashtag开始使用

hashtag复制您的嵌入脚本 URL

hashtag将脚本添加到您的 HTML

hashtag如果您的文档需要身份验证

hashtag验证

hashtag可选地配置嵌入

hashtag控制小部件可见性

hashtag以编程方式导航和交互

hashtag动态加载嵌入脚本

hashtagAPI 参考

hashtag初始化

hashtag小部件控制

hashtag导航

hashtag聊天

hashtag配置

hashtag配置选项

hashtagtabs

hashtagactions

hashtaggreeting

hashtagsuggestions

hashtagtrademark

hashtagtools

hashtagbutton

hashtagvisitor （已认证访问）

hashtag常见陷阱