# 脚本标签将 GitBook Assistant 嵌入到你的网站或应用中的最简单集成方法，是在 HTML 中包含一个独立脚本。每个 GitBook 文档站点都会提供一个可直接使用的嵌入脚本，它会自动加载该组件并将其连接到你的文档。本页将告诉你如何操作。不需要 SDK、构建步骤或框架集成。只需包含该脚本，组件就会出现在你的页面上。 ## 开始使用 {% stepper %} {% step %} ### 复制你的嵌入脚本 URL 在 GitBook 应用中进入你的文档站点，导航到 **设置** 标签页，然后进入 **AI 与 MCP** 并复制嵌入脚本 URL。你也可以手动构建它： ``` https://YOUR_DOCS_DOMAIN/~gitbook/embed/script.js ``` 将你的 `YOUR_DOCS_DOMAIN` 替换为你的真实文档站点域名。 {% endstep %} {% step %} ### 将脚本添加到你的 HTML 中在你的页面 HTML 中添加以下标签。将它放在 `` 中，或者放在 ``. ```html ``` {% endstep %} {% step %} ### 如果你的文档需要身份验证如果你的文档 [受身份验证保护](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/publishing-documentation/authenticated-access)，该脚本必须包含一个已签名的 JWT 令牌。将它作为查询参数附加： ```html ``` {% endstep %} {% step %} ### 验证重新加载你的页面。该组件应出现在右下角。 {% endstep %} {% endstepper %} ### 可选地配置嵌入你可以在显示组件之前自定义它。调用 `configure` 在脚本加载之后，并在调用 `window.GitBook('show')`. ```html ``` 使用此方法，你可以自定义： * 按钮标签和图标 * 组件内可见的标签页 * 自定义操作按钮 * 问候标题和副标题 * 向用户显示的建议提示。 ### 控制组件可见性你可以通过 API 在运行时控制可见性和状态。 ```html ``` 当你想将组件连接到自己的 UI 触发器时，这非常有用。 ### 以编程方式导航和交互你可以通过代码驱动该组件进行导航、切换标签页或发送消息。 ```html ``` 此功能的典型用途包括： * 从你的应用添加指向文档页面的深链接 * 预填一个问题 * 在不同流程之间重置对话 ### 动态加载嵌入脚本如果你只想有条件地加载该组件，或者需要在运行时附加身份验证令牌，请以编程方式注入该脚本。 ```html ``` 当组件应仅在用户操作后或由功能标记控制时加载，请使用此模式 ## API 参考 ### 初始化 * `GitBook('init', options: { siteURL: string }, frameOptions?: { visitor?: {...} })` - 使用站点 URL 和可选的已认证访问初始化组件 ### 小部件控制 * `GitBook('show')` - 显示组件按钮 * `GitBook('hide')` - 隐藏组件按钮 * `GitBook('open')` - 打开组件窗口 * `GitBook('close')` - 关闭组件窗口 * `GitBook('toggle')` - 切换组件窗口 ### 导航 * `GitBook('navigateToPage', path: string)` - 导航到文档标签页中的特定页面 * `GitBook('navigateToAssistant')` - 导航到助手标签页 ### 聊天 * `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 图标](https://fontawesome.com/search) 都受支持 * `label`: `字符串` - 按钮标签文本 * `onClick`: `() => void | Promise` - 点击时的回调函数 ### `greeting` 显示在 Assistant 标签页中的欢迎消息。 * **输入**: `{ title: string, subtitle: string }` ### `suggestions` 显示在 Assistant 欢迎界面中的建议问题。 * **输入**: `string[]` ### `trademark` 在嵌入 UI 中显示或隐藏 GitBook 商标——包括 Docs Embed 页脚和 Assistant 品牌标识。 * **输入**: `boolean` * **默认**: `true` * **示例**: ```javascript window.GitBook('configure', { trademark: false }); ``` ### `tools` 用于扩展 Assistant 的自定义 AI 工具。详情请参见 [创建自定义工具](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/publishing-documentation/embedding/configuration/creating-custom-tools) 。 * **输入**: `Array<{ name: string, description: string, inputSchema: object, execute: Function, confirmation?: {...} }>` ### `按钮` 配置用于启动嵌入的组件按钮（仅限独立脚本）。这使你可以自定义出现在页面右下角按钮的标签和图标。 * **输入**: `{ label: string, icon: 'assistant' | 'sparkle' | 'help' | 'book' }` * **属性**: * `label`: `字符串` - 按钮上显示的文本 * `icon`: `'assistant' | 'sparkle' | 'help' | 'book'` - 按钮上显示的图标 * `assistant` - 助手图标 * `sparkle` - 闪光图标 * `help` - 帮助/问题图标 * `book` - 书本图标 **示例：** ```javascript window.GitBook('configure', { button: { label: '提问', icon: 'assistant' } }); ``` {% hint style="info" %} **注意：** 此选项仅在使用独立 script 标签实现时可用。对于 React 或 Node.js 实现，你需要创建自己的按钮来触发嵌入。 {% endhint %} ### `visitor` （已认证访问）在使用以下方式初始化时传入 `GitBook('init', options, frameOptions)`。用于 [自适应内容](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/publishing-documentation/adaptive-content) 并在 [已认证访问](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/publishing-documentation/authenticated-access). * **输入**: `{ token?: string, unsignedClaims?: Record }` * **属性**: * `token`: `字符串` （可选）- 已签名的 JWT 令牌 * `unsignedClaims`: `Record` （可选）- 用于动态表达式的未签名声明 ## 常见问题 * **脚本 URL 不正确** – 请确保你使用的是实际的文档 URL，而不是示例 `docs.company.com`. * **在脚本加载前调用 GitBook** – 将 API 调用包装在 `script.onload` 中，或将它们放在 script 标签之后。 * **无法访问需要认证的文档** – 如果你的文档需要登录，你必须提供 `visitor.token` 在初始化时。参见 [与已认证文档一起使用](https://gitbook-v2-q67etdj25-gitbook.vercel.app/url/gitbook.com/docs/documentation/zh/publishing-documentation/embedding/using-with-authenticated-docs). * **CORS 或 CSP 错误** – 确保你站点的内容安全策略允许从你的 GitBook 域加载脚本和 iframe。 * **组件不可见** – 检查页面中与其他元素的 z-index 冲突。该组件默认使用较高的 z-index。 * **忘记初始化** – 请确保调用 `GitBook('init', { siteURL: '...' })` 之后再使用其他方法。