安装小组件

只需一个脚本标签。无需构建步骤，无需安装任何包，也无需框架集成。

代码片段

<script
  src="https://widget.minaya.ai/widget.js"
  data-site-key="your-site-key"
  data-api-url="https://api.minaya.ai"
  async
></script>

从仪表盘的 安装与嵌入 页面复制带有您真实站点密钥的版本，并将其放置在结束的 </body> 标签之前。

属性

属性	是否必需	用途
`src`	是	脚本的服务来源（一个 CDN）。
`data-site-key`	是	标识您的企业。该值是公开的，但仅在已加入白名单的域名上生效。
`data-api-url`	是	您的 Minaya 后端地址。与 `src` 相互独立——脚本与 API 可以位于不同的主机上。
`async`	推荐	避免脚本阻塞页面渲染。

data-api-url 必须指向您的 API，而不是提供脚本的 CDN。指向 CDN 会导致每个请求都返回 403，因为该主机上没有 API。

框架说明

Next.js

import Script from "next/script";

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://widget.minaya.ai/widget.js"
          data-site-key="your-site-key"
          data-api-url="https://api.minaya.ai"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

WordPress

将代码片段粘贴到主题的页脚模板中，或使用一款 “页眉页脚脚本”插件。添加到子主题中可以使其在更新后依然保留。

Shopify

将其添加到 theme.liquid 中，紧靠在 </body> 之前。

单页应用

小组件只会挂载一次，并在客户端路由切换期间持续存在。请勿在每个路由中重复挂载。

域名白名单

小组件仅在您于仪表盘中列出的来源上生效。请包含访客使用的每一个主机：

https://example.com
https://www.example.com
https://staging.example.com

来源采用精确匹配，因此 example.com 与 www.example.com 属于不同的条目。

故障排查

现象	原因
请求返回 `403`	来源未加入白名单，或 `data-api-url` 指向了 CDN。
没有任何内容出现	脚本未能加载，或缺少 `data-site-key`。请检查控制台。
颜色不正确	配置会被短暂缓存；保存更改后请强制刷新。
小组件被其他元素遮挡	通过自定义 CSS提高其 `z-index`。

轮换站点密钥

轮换会立即使旧密钥失效，所有现有嵌入都会停止工作，因此请在同一次更改中同步更新您的代码片段。