网页组件集成

AiWma Web Widget 是最快的 ACS 接入方式——在您的网页 </body> 之前插入两行代码，即可获得完整的 AI 客服气泡界面，无需搭建任何前端组件。

最简接入（2 行代码）

将以下代码粘贴到您 HTML 页面的 </body> 标签之前：

        
html在 </body> 前添加
        <script>
  window.AiWmaConfig = { apiKey: 'aiwma_prod_YOUR_CLIENT_CODE_xxxxxxxx' };
</script>
<script src="https://cdn.aiwma.com/widget/v1/widget.js" async></script>
      

完成后刷新页面，您将在页面右下角看到 AiWma 的 AI 客服气泡。 点击气泡即可开始对话。首次加载 Widget 脚本约 45KB，后续通过缓存加速。

配置项

通过 window.AiWmaConfig 对象控制 Widget 的行为和外观：

        
javascript完整配置示例
        window.AiWmaConfig = {
  // 必填
  apiKey: 'aiwma_prod_xmohe_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',

  // 外观
  position:    'bottom-right',  // 'bottom-right' | 'bottom-left'
  primaryColor: '#E8703A',      // 气泡与发送按钮的主色
  botName:     '魔盒客服',        // 气泡头部显示的机器人名称
  botAvatar:   'https://your-cdn.com/avatar.png', // 机器人头像 URL

  // 欢迎语（首次打开时显示）
  greeting: '您好！我是魔盒客服，有什么可以帮您的？',

  // 渠道（固定传 web_widget，无需修改）
  channel: 'web_widget',

  // 用户标识（可选，用于统计和 CRM 关联）
  // 注意：此值会在平台内部哈希处理，不会明文存储
  userId: 'your-internal-user-id',

  // 声音模式（true = 用户可语音输入）
  voiceEnabled: true,

  // 语言
  locale: 'zh-CN',

  // 事件回调（见下方事件说明）
  onOpen:       function() { console.log('widget opened'); },
  onClose:      function() { console.log('widget closed'); },
  onMessage:    function(msg) { console.log('new message', msg); },
  onHandover:   function(info) { console.log('handover triggered', info); },
  onSessionEnd: function(session) { console.log('session ended', session); },
};
      

可用事件回调

JavaScript API

Widget 加载完成后，您可以通过 window.AiWma 对象以编程方式控制 Widget：

        
javascriptWidget API
        // 等待 Widget 就绪
window.AiWmaReady = function() {
  const widget = window.AiWma;

  widget.open();    // 展开聊天窗口
  widget.close();   // 收起聊天窗口
  widget.toggle();  // 切换展开/收起

  // 主动发送一条消息（模拟用户输入）
  widget.sendMessage('我的订单号是 ORD-20260528-001');

  // 获取当前会话 ID
  const sessionId = widget.getSessionId();

  // 销毁 Widget（从 DOM 移除）
  widget.destroy();
};
      

React / Vue 中使用

Widget 是纯 JavaScript 实现，与任何框架兼容。以 React 为例：

        
jsxReact 示例
        import { useEffect } from 'react';

export function AiWmaWidget({ userId }) {
  useEffect(() => {
    // 挂载配置
    window.AiWmaConfig = {
      apiKey:    process.env.REACT_APP_AIWMA_API_KEY,
      userId:    userId,
      botName:   '智能客服',
      voiceEnabled: true,
      onHandover: (info) => {
        // 通知您的 CRM 有转人工需求
        yourCrm.createTicket({ sessionId: info.sessionId });
      },
    };

    // 动态加载 Widget 脚本（避免 SSR 问题）
    if (!document.getElementById('aiwma-widget-script')) {
      const script = document.createElement('script');
      script.id  = 'aiwma-widget-script';
      script.src = 'https://cdn.aiwma.com/widget/v1/widget.js';
      script.async = true;
      document.body.appendChild(script);
    }

    return () => {
      // 组件卸载时销毁 Widget
      window.AiWma?.destroy();
    };
  }, [userId]);

  return null; // Widget 自行挂载到 body
}
      

Content Security Policy（CSP）配置

如果您的网站启用了严格的 CSP，需要将以下来源加入白名单：

        
http header需要添加的 CSP 指令
        Content-Security-Policy:
  script-src  'self' https://cdn.aiwma.com;
  connect-src 'self' https://api.aiwma.com wss://api.aiwma.com;
  img-src     'self' https://cdn.aiwma.com data:;
  style-src   'self' 'unsafe-inline' https://cdn.aiwma.com;
      

常见问题

Q：气泡没有出现，怎么排查？

打开浏览器控制台，搜索 [AiWma] 前缀的日志。常见原因： API Key 格式错误（检查有无多余空格）、CDN 加载失败（检查网络连接）、 CSP 阻止了脚本加载。

Q：如何在测试环境中使用 Widget？

将 API Key 替换为 aiwma_dev_ 前缀的开发环境 Key。 开发环境的对话数据不计入生产配额，日志更详细。

Q：Widget 支持自定义 CSS 覆盖吗？

Widget 使用 Shadow DOM 隔离样式，外部 CSS 无法直接穿透。 请通过 primaryColor、botAvatar 等配置参数进行外观定制。深度定制（自定义气泡形状、布局）请联系 AiWma 技术团队获取企业版配置选项。