Mintlify 小组件

助手可回答关于你 Mintlify 站点的问题。若要在其他站点或 Web 应用中嵌入相同能力,请使用小组件。借助小组件,你可以在产品仪表板、营销站点、支持门户或其他位置为用户提供基于你内容训练的 AI 聊天服务。

通过一段托管脚本,即可将小组件添加到任何网站或 Web 应用。小组件自带触发器,并在封闭的 Shadow DOM 内渲染,可防止你的应用样式影响小组件。

浏览器端唯一必需的选项是公共小组件 ID。启用状态、允许的来源、附件、机器人防护以及分流联系表单均可在仪表板中管理。可在浏览器配置中设置针对该嵌入的起始问题和支持邮箱。

• Pro 或 Enterprise 套餐。小组件与助手共用同一额度。

1. 前往你部署的 Widget 页面。
2. 启用小组件。
3. 添加嵌入小组件的允许来源。
4. 复制小组件 ID。

使用交互式面板配置小组件的展示方式、视觉选项和观察者钩子。每次更改选项时,安装代码块都会随之更新。

将生成的代码添加到站点后,重新加载页面。确认触发器已显示,然后点击它并发送一个测试问题,以验证小组件是否已连接。

将 defaultOpen 设为 true,可在首次挂载后立即打开小组件:

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  defaultOpen: true,
});

defaultOpen 默认为 false,且仅在首次初始化时生效。若访客关闭小组件后,再次以相同的小组件 ID 和 API 端点调用 init() 并不会重新打开它。初始化之后请使用 open() 和 close() 来控制它。

在调用其他方法前请先等待 init() 完成。你可以保留内置触发器,也可以从应用中任意按钮打开已配置的展示形式。

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  supportEmail: "hi@mintlify.com",
  starterQuestions: [
    "How do I get started with Mintlify?",
    "How do I customize my docs?",
    "How do I deploy my docs?",
  ],
});

document.querySelector("#help-button").addEventListener("click", () => {
  void window.MintlifyAssistant.open({
    source: "help-button",
    focus: true,
  });
});

若要打开小组件并立即发送问题,请调用 ask():

await window.MintlifyAssistant.ask("How do I authenticate?", {
  source: "authentication-guide",
  open: true,
  focus: true,
});

事件元数据和请求中会包含 source 值,便于你区分内置交互与自定义入口。

使用 update() 可在不清除当前会话的情况下更改外观、文案、支持邮箱、起始问题或钩子。只有传入的字段会被更改。

await window.MintlifyAssistant.update({
  appearance: {
    theme: "dark",
    accent: "#7c3aed",
  },
  labels: {
    title: "Docs copilot",
    trigger: "Ask docs",
  },
  supportEmail: "support@example.com",
  starterQuestions: [
    "How do I get started?",
    "How do I manage my account?",
  ],
});

传入 null 可将某个字段或分组恢复为默认值、移除支持邮箱,或将起始问题列表恢复为空:

await window.MintlifyAssistant.update({
  appearance: {
    accent: null,
  },
  supportEmail: null,
  starterQuestions: null,
  hooks: null,
});

更改 identity 会开启新的会话。更改小组件 ID 或 API 端点则需要先调用 destroy(),再执行新的 init()。

你可以在初始化时提供 supportEmail 和 starterQuestions,也可以稍后通过 update() 更改。这些值仅作用于当前嵌入,不会继承自你的 Mintlify 仪表板。

当你的文档按语言或版本组织时,使用 filter 来限定助手检索的范围。省略某个字段即可对该字段的所有取值进行检索。

await window.MintlifyAssistant.init({
  id: "YOUR_WIDGET_ID",
  filter: {
    language: "en",
    version: "v2",
  },
});

language 必须是受支持的语言代码,例如 en、es、fr 或 zh-Hans。version 与你在仪表板中配置的版本名称一致。

当访客在你的应用中切换语言或版本时,可通过 update() 在运行时更改筛选条件:

await window.MintlifyAssistant.update({
  filter: {
    language: "fr",
    version: null,
  },
});

对某个字段传入 null 可清除该筛选条件,传入 filter: null 可同时清除两个筛选条件。

将该对象传入 init()。

不支持任意 CSS 和中性色板覆盖。封闭的 Shadow DOM 可同时保护你的应用与小组件,防止跨站样式回归。

hooks: {
  event(event) {
    console.log(event.type, event.actor, event.source);
  },
  error(error) {
    console.error(error.code, error.retryable, error.status);
  },
}

event 钩子会接收 init、open、close、ask、update、reset、navigate 和 destroy 的生命周期与交互元数据。事件不包含问题文本、身份、会话或 CAPTCHA 令牌。

error 钩子会接收稳定的 code、一个 retryable 布尔值以及可选的 HTTP status。任一钩子抛出的异常都不会中断小组件。

将该可选对象传入 open()。

将该可选对象作为问题字符串之后的参数传入 ask()。

将该对象传入 update()。所有字段均为可选,null 表示恢复默认值。

会话快照始终保留在小组件内部。每个方法都会 resolve 为 void。

如果你的站点使用了内容安全策略(CSP),请为所启用的小组件功能允许以下来源:

即使采用严格的 script-src 策略,也必须同时授权加载器和初始化脚本。严格的 style-src 策略必须授权你传入 init() 的 nonce,小组件会将其复制到注入的样式表上。向 init() 传入 nonce 时,仅会将其传播到小组件在初始化之后创建的资源。