脚本标签

了解如何使用单个脚本标签将 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
    },
    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: 字符串 - 图标名称。任何 FontAwesome 图标均受支持
- label: 字符串 - 按钮标签文本
- onClick: () => void | Promise<void> - 点击时的回调函数

`greeting`

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

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

`suggestions`

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

类型: 字符串数组

`tools`

用于扩展助手的自定义 AI 工具。详见创建自定义工具部分了解详情。

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

`button`

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

类型: { label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }
属性:
- label: 字符串 - 显示在按钮上的文本
- 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: 字符串 （可选）- 签名的 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: '...' }) 。

最后更新于2天前

这有帮助吗？

下午好

hashtag开始使用

hashtag复制您的嵌入脚本 URL

hashtag将脚本添加到您的 HTML

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

hashtag验证

hashtag可选地配置嵌入

hashtag控制小部件可见性

hashtag以编程方式导航和交互

hashtag动态加载嵌入脚本

hashtagAPI 参考

hashtag初始化

hashtag小部件控制

hashtag导航

hashtag聊天

hashtag配置

hashtag配置选项

hashtagtabs

hashtagactions

hashtaggreeting

hashtagsuggestions

hashtagtools

hashtagbutton

hashtagvisitor （已认证访问）

hashtag常见陷阱